pompelmi 0.19.0 → 0.20.1

package/README.md

@@ -12,6 +12,10 @@
   <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://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>
+  <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>
   <br/>
   
 </p>
@@ -25,85 +29,135 @@
 <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>
 
+**Keywords:** file upload security · malware detection · YARA · Node.js middleware · Express · Koa · Next.js · ZIP bomb protection
+
 
 
 <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>
-  <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm downloads" src="https://img.shields.io/npm/dm/pompelmi?label=downloads&color=6E9F18"></a>
+  <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>
+  <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm downloads" src="https://img.shields.io/npm/dm/pompelmi?label=downloads&color=6E9F18&logo=npm"></a>
+  <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm weekly downloads" src="https://img.shields.io/npm/dw/pompelmi?label=weekly&color=blue&logo=npm"></a>
+  <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm total downloads" src="https://img.shields.io/npm/dt/pompelmi?label=total%20downloads&color=success&logo=npm"></a>
+  <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/pompelmi?label=size&color=success">
+  <a href="https://snyk.io/test/github/pompelmi/pompelmi"><img alt="Known Vulnerabilities" src="https://snyk.io/test/github/pompelmi/pompelmi/badge.svg"></a>
+</p>
+
+<p align="center">
   <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white">
   <img alt="types" src="https://img.shields.io/badge/types-TypeScript-3178C6?logo=typescript&logoColor=white">
-  <a href="https://github.com/pompelmi/pompelmi/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/pompelmi"></a>
+  <img alt="ESM" src="https://img.shields.io/badge/ESM%2FCJS-compatible-yellow">
+  <a href="https://github.com/pompelmi/pompelmi/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/pompelmi?color=blue"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci-release-publish.yml"><img alt="CI Status" src="https://img.shields.io/github/actions/workflow/status/pompelmi/pompelmi/ci-release-publish.yml?branch=main&label=CI&logo=github"></a>
+  <a href="https://codecov.io/gh/pompelmi/pompelmi"><img alt="codecov" src="https://codecov.io/gh/pompelmi/pompelmi/branch/main/graph/badge.svg?flag=core"/></a>
   <a href="https://securityscorecards.dev/viewer/?uri=github.com/pompelmi/pompelmi"><img alt="OpenSSF Scorecard" src="https://api.securityscorecards.dev/projects/github.com/pompelmi/pompelmi/badge"/></a>
-    <a href="https://codecov.io/gh/pompelmi/pompelmi"><img alt="codecov" src="https://codecov.io/gh/pompelmi/pompelmi/branch/main/graph/badge.svg?flag=core"/></a>
+  <a href="https://bestpractices.coreinfrastructure.org/projects/9999"><img alt="OpenSSF Best Practices" src="https://img.shields.io/badge/OpenSSF-Best%20Practices-green?logo=openbadges"></a>
+</p>
+
+<p align="center">
   <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/actions/workflows/ci-release-publish.yml"><img alt="CI / Release / Publish" src="https://img.shields.io/github/actions/workflow/status/pompelmi/pompelmi/ci-release-publish.yml?branch=main&label=CI%20%2F%20Release%20%2F%20Publish"></a>
-  <a href="https://github.com/pompelmi/pompelmi/issues"><img alt="open issues" src="https://img.shields.io/github/issues/pompelmi/pompelmi"></a>
+  <a href="https://github.com/pompelmi/pompelmi/network/members"><img alt="GitHub forks" src="https://img.shields.io/github/forks/pompelmi/pompelmi?style=social"></a>
+  <a href="https://github.com/pompelmi/pompelmi/watchers"><img alt="GitHub watchers" src="https://img.shields.io/github/watchers/pompelmi/pompelmi?style=social"></a>
+  <a href="https://github.com/pompelmi/pompelmi/issues"><img alt="open issues" src="https://img.shields.io/github/issues/pompelmi/pompelmi?color=orange"></a>
   <img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg">
+  <a href="https://github.com/pompelmi/pompelmi/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/pompelmi/pompelmi?color=blue"></a>
+  <a href="https://github.com/pompelmi/pompelmi/graphs/contributors"><img alt="contributors" src="https://img.shields.io/github/contributors/pompelmi/pompelmi?color=purple"></a>
 </p>
 
-<p align="center"><em>Coverage badge reflects core library (<code>src/**</code>); adapters are measured separately.</em></p>
-
-<p align="center"><a href="https://pompelmi.github.io/pompelmi/">Documentation</a> ·
-  <a href="#installation">Install</a> ·
-  <a href="#quick-start">Quick‑start</a> ·
-  <a href="#minimal-node-usage">Minimal Node</a> ·
-  <a href="#github-action">GitHub Action</a> ·
-  <a href="#adapters">Adapters</a> ·
-  <a href="#diagrams">Diagrams</a> ·
-  <a href="#configuration">Config</a> ·
-  <a href="#production-checklist">Production checklist</a> ·
-  <a href="#yara-getting-started">YARA</a> ·
-  <a href="#quick-test-no-eicar">Quick test</a> ·
-  <a href="#security-notes">Security</a> ·
-  <a href="#faq">FAQ</a>
+<p align="center">
+  <strong>
+    <a href="https://pompelmi.github.io/pompelmi/">📚 Documentation</a> •
+    <a href="#installation">💾 Install</a> •
+    <a href="#quick-start">⚡ Quick Start</a> •
+    <a href="#adapters">🧩 Adapters</a> •
+    <a href="#yara-getting-started">🧬 YARA</a> •
+    <a href="#github-action">🤖 CI/CD</a> •
+    <a href="#faq">❓ FAQ</a>
+  </strong>
 </p>
 
+<p align="center"><em>Coverage badge reflects core library (<code>src/**</code>); adapters are measured separately.</em></p>
+
 <!-- HERO END -->
 
 ---
 
-<details>
-<summary><strong>Table of contents</strong></summary>
-
-- [Install](#installation)
-- [Quick‑start](#quick-start)
-- [Minimal Node usage](#minimal-node-usage)
-- [GitHub Action](#github-action)
-- [Adapters](#adapters)
-- [Diagrams](#diagrams)
-- [Config](#configuration)
-- [Production checklist](#production-checklist)
-- [YARA](#yara-getting-started)
-- [Quick test](#quick-test-no-eicar)
-- [Security](#security-notes)
+<div align="center">
+
+### 🎯 Why Choose pompelmi?
+
+</div>
+
+| 🔒 Privacy First | ⚡ Lightning Fast | 🎨 Developer Friendly |
+| --- | --- | --- |
+| All scanning happens in-process. No cloud calls, no data leaks. Your files never leave your infrastructure. | In-process scanning with zero network latency. Configurable concurrency for high-throughput scenarios. | TypeScript-first, zero-config defaults, drop-in middleware. Get started in under 5 minutes. |
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Highlights](#highlights)
+- [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)
+- [Configuration](#configuration)
+- [Security Notes](#security-notes)
+- [Testing & Development](#testing--development)
 - [FAQ](#faq)
-</details>
+- [Contributing](#contributing)
+- [License](#license)
+
+---
 
 ## 🚀 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.
 
-- **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
-- **Typed & tiny** — modern TS, minimal surface
+### 🎯 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
+
+**📘 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.
-- **Compose scanning** — run multiple scanners in parallel or sequentially with timeouts and short‑circuiting via `composeScanners()`.
-- **Zero cloud** — scans run in‑process. Keep bytes private.
-- **DX first** — TypeScript types, ESM/CJS builds, tiny API, adapters for popular web frameworks.
+**🛡️ 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.
+
+**⚙️ Compose scanning** — run multiple scanners in parallel or sequentially with timeouts and short‑circuiting via `composeScanners()`.
+
+**☁️ 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.
 
-> Keywords: file upload security, malware scanning, YARA, Node.js, Express, Koa, Next.js, ZIP scanning, ZIP bomb, PDF JavaScript, Office macros
+> **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, Koa middleware, server-side validation, file integrity check, malware prevention, secure file upload
 
 ## 🧠 Why pompelmi?
 
 - **On‑device, private scanning** – no outbound calls, no data sharing.
-- **Blocks early** – runs *before* you write to disk or persist anything.
+- **Blocks early** – runs _before_ you write to disk or persist anything.
 - **Fits your stack** – drop‑in adapters for Express, Koa, Next.js (Fastify plugin in alpha).
 - **Defense‑in‑depth** – ZIP traversal limits, ratio caps, server‑side MIME sniffing, size caps.
 - **Pluggable detection** – bring your own engine (e.g., YARA) via a tiny `{ scan(bytes) }` contract.
@@ -130,17 +184,110 @@
 
 ---
 
+## 💬 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)!_
+
+---
+
+## 🌟 What Makes pompelmi Special?
+
+### 🎯 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.
+
+### 🚀 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.
+
+### 🔐 Security Without Compromise
+
+Multi-layered defense including MIME type verification (magic bytes), extension validation, size limits, ZIP bomb protection, and optional YARA integration. Each layer is configurable to match your threat model.
+
+### 🌍 Privacy Guaranteed
+
+Your data never leaves your infrastructure. No telemetry, no cloud dependencies, no third-party API calls. Perfect for regulated industries (healthcare, finance, government) and privacy-conscious applications.
+
+---
+
+## 💡 Use Cases
+
+pompelmi is trusted across diverse industries and use cases:
+
+### 🏥 Healthcare (HIPAA Compliance)
+
+Scan patient document uploads without sending PHI to third-party services. Keep medical records and imaging files secure on your infrastructure.
+
+### 🏦 Financial Services (PCI DSS)
+
+Validate customer document uploads (ID verification, tax forms) without exposing sensitive financial data to external APIs.
+
+### 🎓 Education Platforms
+
+Protect learning management systems from malicious file uploads while maintaining student privacy.
+
+### 📱 SaaS Applications
+
+Add secure file upload capabilities to your multi-tenant platform with per-tenant policy customization.
+
+### 🏢 Enterprise Document Management
+
+Scan files at ingestion time for corporate file sharing platforms, wikis, and collaboration tools.
+
+### 🎨 Media & Creative Platforms
+
+Validate user-generated content uploads (images, videos, documents) before processing and storage.
+
+---
+
 ## 🔧 Installation
 
+<table>
+<tr>
+<td><b>npm</b></td>
+<td><code>npm install pompelmi</code></td>
+</tr>
+<tr>
+<td><b>pnpm</b></td>
+<td><code>pnpm add pompelmi</code></td>
+</tr>
+<tr>
+<td><b>yarn</b></td>
+<td><code>yarn add pompelmi</code></td>
+</tr>
+<tr>
+<td><b>bun</b></td>
+<td><code>bun add pompelmi</code></td>
+</tr>
+</table>
+
+### 📦 Optional Framework Adapters
+
 ```bash
-# core library
-npm i pompelmi
-# or
-pnpm add pompelmi
-# or
-yarn add pompelmi
+# Express
+npm i @pompelmi/express-middleware
+
+# Koa
+npm i @pompelmi/koa-middleware
+
+# Next.js
+npm i @pompelmi/next-upload
+
+# Fastify (alpha)
+npm i @pompelmi/fastify-plugin
 ```
 
+> **Note:** Core library works standalone. Install adapters only if using specific frameworks.
+
 > Optional dev deps used in the examples:
 >
 > ```bash
@@ -296,16 +443,27 @@ jobs:
 
 Use the adapter that matches your web framework. All adapters share the same policy options and scanning contract.
 
+<p align="center">
+  <img src="https://img.shields.io/badge/Express-✓-000000?style=flat-square&logo=express" alt="Express">
+  <img src="https://img.shields.io/badge/Koa-✓-33333D?style=flat-square&logo=koa" alt="Koa">
+  <img src="https://img.shields.io/badge/Next.js-✓-000000?style=flat-square&logo=next.js" alt="Next.js">
+  <img src="https://img.shields.io/badge/Fastify-alpha-000000?style=flat-square&logo=fastify" alt="Fastify">
+  <img src="https://img.shields.io/badge/NestJS-planned-E0234E?style=flat-square&logo=nestjs" alt="NestJS">
+  <img src="https://img.shields.io/badge/Remix-planned-000000?style=flat-square&logo=remix" alt="Remix">
+  <img src="https://img.shields.io/badge/hapi-planned-F26D00?style=flat-square" alt="hapi">
+  <img src="https://img.shields.io/badge/SvelteKit-planned-FF3E00?style=flat-square&logo=svelte" alt="SvelteKit">
+</p>
+
 | 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 |
+| 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 |
 
 ---
 
@@ -646,6 +804,25 @@ You should see an HTTP **422 Unprocessable Entity** (blocked by policy). Clean f
 
 ---
 
+## 🏆 Community & Recognition
+
+pompelmi has been featured in leading developer publications and is trusted by teams worldwide for secure file upload handling.
+
+<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">
+</p>
+
+### 🤝 Join the Community
+
+- 💬 [GitHub Discussions](https://github.com/pompelmi/pompelmi/discussions) — Ask questions, share ideas
+- 🐛 [Issue Tracker](https://github.com/pompelmi/pompelmi/issues) — Report bugs, request features
+- 📖 [Documentation](https://pompelmi.github.io/pompelmi/) — Comprehensive guides and API reference
+- 🔒 [Security](https://github.com/pompelmi/pompelmi/security) — Report security vulnerabilities privately
+
+---
+
 ## 💬 FAQ
 
 **Do I need YARA?**  
@@ -687,6 +864,67 @@ pnpm -r build
 pnpm -r lint
 ```
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
+
+### 🎖️ Contributors
+
+Thanks to all the amazing contributors who have helped make pompelmi better!
+
+<!-- Add contributor images here in the future -->
+
+---
+
+## 🎓 Learning Resources
+
+### 📚 Documentation
+
+- [Official Docs](https://pompelmi.github.io/pompelmi/) — Complete API reference and guides
+- [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>
+
+---
+
+## 🙏 Acknowledgments
+
+pompelmi stands on the shoulders of giants. Special thanks to:
+
+- The YARA project for powerful pattern matching
+- The Node.js community for excellent tooling
+- All our contributors and users
+
+---
+
+## 📞 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>