pompelmi 0.35.2 → 0.35.3

package/README.md

@@ -1,29 +1,70 @@
-# Pompelmi
+<div align="center">
+  <img src="./assets/logo.svg" alt="Pompelmi logo" width="144" />
+
+  <h1>Pompelmi</h1>
+
+  <p><strong>Route-level upload security for Node.js.</strong></p>
+
+  <p>Inspect untrusted uploads before storage.</p>
+
+  <p>
+    MIME and extension spoofing · archive abuse · risky document and binary
+    signals · optional YARA
+  </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>
+  </p>
+
+  <p><sub>Open-source core · MIT · Node.js 18+</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://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>
+  </p>
+
+  <p>
+    <a href="https://pompelmi.github.io/pompelmi/getting-started/"><strong>Getting started</strong></a>
+    ·
+    <a href="https://pompelmi.github.io/pompelmi/#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>
+</div>
+
+<p align="center">
+  Mentioned by <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>,
+  and
+  <a href="https://github.com/dzharii/awesome-typescript">Awesome TypeScript</a>.
+</p>
 
-In-process file upload security for Node.js. Inspect untrusted files before storage so your application can reject, quarantine, or accept with context.
-
-[![npm version](https://img.shields.io/npm/v/pompelmi)](https://www.npmjs.com/package/pompelmi)
-[![CI](https://img.shields.io/github/actions/workflow/status/pompelmi/pompelmi/ci.yml?label=ci)](https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml)
-[![GitHub stars](https://img.shields.io/github/stars/pompelmi/pompelmi)](https://github.com/pompelmi/pompelmi/stargazers)
+## Quick Start
 
-Pompelmi helps reduce:
+Install the core package:
 
-- MIME / extension spoofing and magic-byte mismatches
-- risky archive structures such as ZIP bombs, traversal, and deep nesting
-- risky document and binary patterns such as PDF actions, Office macro hints, PE signatures, and polyglot files
-- store-first upload flows that need a clean / suspicious / malicious verdict before persistence
-- known malicious matches when you plug in YARA or another scanner
+```bash
+npm install pompelmi
+```
 
-Install: `npm install pompelmi`
-
-## Quick Start
+Minimal route-level example:
 
 ```ts
 import { scanBytes, STRICT_PUBLIC_UPLOAD } from 'pompelmi';
 
-const report = await scanBytes(file.buffer, {
-  filename: file.originalname,
-  mimeType: file.mimetype,
+const report = await scanBytes(req.file.buffer, {
+  filename: req.file.originalname,
+  mimeType: req.file.mimetype,
   policy: STRICT_PUBLIC_UPLOAD,
   failClosed: true,
 });
@@ -35,17 +76,27 @@ if (report.verdict !== 'clean') {
     reasons: report.reasons,
   });
 }
+
+return res.status(200).json({ verdict: report.verdict });
 ```
 
-Need a local scan in under a minute? Start with [Getting started](https://pompelmi.github.io/pompelmi/getting-started/). Want a preview of the verdict flow first? Open the [browser preview](https://pompelmi.github.io/pompelmi/#browser-preview). Want a minimal server route? See [examples/demo](./examples/demo).
+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).
 
-If Pompelmi fits the way you handle upload risk, a GitHub star helps more Node.js teams find the project.
+If Pompelmi matches how you want upload security to work, star the repo so more Node.js teams can find it.
 
 ## Why It Exists
 
-Upload endpoints are part of your attack surface. A file can look harmless at the form layer and only become dangerous after storage, extraction, rendering, or downstream parsing.
+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.
+
+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
 
-Pompelmi keeps the first decision inside the application path, where the route still knows the file class, the trust level, and the right failure mode.
+- 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
 
@@ -55,9 +106,18 @@ Pompelmi keeps the first decision inside the application path, where the route s
 - document, image, and archive routes that need different policies
 - CI/CD or internal artifact scanning before promotion
 
+## Why Not Just X?
+
+| 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
 
-- Express: [Docs](https://pompelmi.github.io/pompelmi/how-to/express/) · [Example](./examples/express-minimal)
+- 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)
@@ -66,65 +126,27 @@ Pompelmi keeps the first decision inside the application path, where the route s
 - 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/)
 
-## Docs and Examples
+## Demo, Preview, and Examples
+
+![Pompelmi upload security demo](assets/malware-detection-node-demo.gif)
+
+- [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
+
+## 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/)
-- [Examples index](./examples/README.md)
-- [Demo example](./examples/demo)
 - [Featured in](https://pompelmi.github.io/pompelmi/featured-in/)
 - [Translations](https://pompelmi.github.io/pompelmi/translations/)
-- [Contributing](./CONTRIBUTING.md)
-- [Security](./SECURITY.md)
-- [Roadmap](./ROADMAP.md)
 
-## Demo
+## Enterprise and Commercial Support
 
-![Pompelmi demo](assets/malware-detection-node-demo.gif)
-
-The website includes a client-side [browser preview](https://pompelmi.github.io/pompelmi/#browser-preview) for fast evaluation. The repo also ships a minimal [Express upload gate demo](./examples/demo) that returns `clean`, `suspicious`, or `malicious` before storage.
-
-## What It Checks
-
-Pompelmi is designed for the upload boundary, not as a full antivirus replacement.
-
-It can combine:
-
-- MIME sniffing, magic-byte checks, and extension allowlists
-- archive controls such as ZIP bombs, traversal, entry counts, expansion limits, and nesting limits
-- common heuristics for risky PDFs, Office macro hints, executables, and other suspicious structures
-- optional YARA-based signature matching
-- route-level `clean`, `suspicious`, and `malicious` decisions with quarantine-friendly workflows
-
-## Ecosystem
-
-- `pompelmi`
-- `@pompelmi/express-middleware`
-- `@pompelmi/koa-middleware`
-- `@pompelmi/next-upload`
-- `@pompelmi/nestjs-integration`
-- `@pompelmi/fastify-plugin`
-- `@pompelmi/ui-react`
-- `@pompelmi/cli`
-
-## Repository Layout
-
-- `src/` core library
-- `packages/` framework adapters and supporting packages
-- `examples/` runnable examples
-- `tests/` test coverage
-- `website/` public docs, blog, and discovery site
-
-## Development
-
-```bash
-pnpm install
-pnpm test
-pnpm build
-```
+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/).
 
 <!-- MENTIONS:START -->
 
@@ -157,6 +179,10 @@ Full page: [pompelmi.github.io/pompelmi/featured-in](https://pompelmi.github.io/
 
 <!-- MENTIONS:END -->
 
-## License
+## Project
 
-[MIT](./LICENSE)
+- [Contributing](./CONTRIBUTING.md)
+- [Security](./SECURITY.md)
+- [Roadmap](./ROADMAP.md)
+- [GitHub Discussions](https://github.com/pompelmi/pompelmi/discussions)
+- [License](./LICENSE)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pompelmi",
-  "version": "0.35.2",
-  "description": "Secure file uploads for Node.js. Scan untrusted files before storage with in-process, local-first checks for MIME spoofing, archive bombs, risky document structures, and optional YARA.",
+  "version": "0.35.3",
+  "description": "Inspect untrusted uploads before storage in Node.js. Open-source upload security with checks for spoofing, archive abuse, risky document and binary signals, and optional YARA.",
   "main": "./dist/pompelmi.cjs",
   "module": "./dist/pompelmi.esm.js",
   "type": "module",