pompelmi 0.34.4 → 0.34.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +103 -148
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,193 +1,148 @@
1
1
  <div align="center">
2
+ <img src="assets/logo.svg" alt="Pompelmi logo" width="160" />
3
+ <h1>Pompelmi</h1>
4
+ <p>Local-first file upload scanning for Node.js.</p>
5
+ <p>
6
+ <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi"></a>
7
+ <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>
8
+ <a href="https://github.com/pompelmi/pompelmi/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pompelmi/pompelmi"></a>
9
+ <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm downloads" src="https://img.shields.io/npm/dm/pompelmi"></a>
10
+ </p>
11
+ <p>
12
+ <a href="https://github.com/sorrycc/awesome-javascript"><img alt="Mentioned in Awesome JavaScript" src="https://img.shields.io/badge/mentioned-Awesome%20JavaScript-f59e0b"></a>
13
+ <a href="https://github.com/dzharii/awesome-typescript"><img alt="Mentioned in Awesome TypeScript" src="https://img.shields.io/badge/mentioned-Awesome%20TypeScript-3178C6"></a>
14
+ <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-339933?logo=node.js&logoColor=white"></a>
15
+ <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>
16
+ </p>
17
+ <p>
18
+ <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%20%23124-0A84FF?logo=substack&logoColor=white"></a>
19
+ <a href="https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/"><img alt="Featured on Stack Overflow by Ryan Donovan" src="https://img.shields.io/badge/featured-Stack%20Overflow-F48024?logo=stackoverflow&logoColor=white"></a>
20
+ <a href="https://stackoverflow.blog/newsletter/issue-319-dogfooding-your-sdlc/"><img alt="Featured in The Overflow #319" src="https://img.shields.io/badge/featured-The%20Overflow%20%23319-F48024?logo=stackoverflow&logoColor=white"></a>
21
+ <a href="https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/"><img alt="Featured in Help Net Security" src="https://img.shields.io/badge/featured-Help%20Net%20Security-2563eb"></a>
22
+ </p>
23
+ </div>
2
24
 
3
- <picture>
4
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pompelmi/pompelmi/main/assets/logo.svg">
5
- <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/pompelmi/pompelmi/main/assets/logo.svg">
6
- <img src="https://raw.githubusercontent.com/pompelmi/pompelmi/main/assets/logo.svg" alt="Pompelmi logo" width="220" />
7
- </picture>
8
-
9
- <h1>Pompelmi</h1>
10
-
11
- <p><strong>Stop malicious uploads before they hit storage.</strong></p>
12
-
13
- <p>Secure file upload scanning for Node.js with MIME sniffing, ZIP bomb protection, polyglot detection, risky document checks, and optional YARA.</p>
14
-
15
- <p>
16
- <a href="https://github.com/pompelmi/pompelmi/stargazers"><img alt="Star on GitHub" src="https://img.shields.io/badge/Star%20on%20GitHub-181717?style=for-the-badge&logo=github&logoColor=white"></a>
17
- <a href="#quick-start"><img alt="Start in 60 seconds" src="https://img.shields.io/badge/Start%20in-60%20seconds-059669?style=for-the-badge"></a>
18
- <a href="https://pompelmi.github.io/pompelmi/"><img alt="Read the docs" src="https://img.shields.io/badge/Read%20the-Docs-2563eb?style=for-the-badge"></a>
19
- </p>
20
-
21
- <p><strong>Private by design</strong> • <strong>No cloud API</strong> • <strong>No daemon</strong> • <strong>Express / Next.js / Koa / NestJS / Fastify</strong></p>
22
-
23
- <p>
24
- <a href="https://github.com/pompelmi/pompelmi/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=for-the-badge&logo=github&label=stars"></a>
25
- <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm downloads per month" src="https://img.shields.io/npm/dm/pompelmi?style=for-the-badge&logo=npm&label=downloads%2Fmonth"></a>
26
- <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi?style=for-the-badge&logo=npm&label=npm"></a>
27
- <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?style=for-the-badge&branch=main&label=CI"></a>
28
- </p>
25
+ Pompelmi inspects untrusted files before storage and helps you decide whether to allow, reject, or quarantine them before they reach downstream systems.
29
26
 
30
- <p>
31
- <img alt="Node 18+" src="https://img.shields.io/badge/node-%3E%3D18-339933?style=for-the-badge&logo=node.js&logoColor=white">
32
- <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white">
33
- <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-0f172a?style=for-the-badge">
34
- <img alt="Zero cloud dependency" src="https://img.shields.io/badge/cloud-none-059669?style=for-the-badge">
35
- </p>
27
+ It is built for upload endpoints that cannot rely on filenames, extensions, or client-provided MIME types alone.
36
28
 
37
- <p>
38
- <strong>
39
- <a href="https://pompelmi.github.io/pompelmi/">Docs</a> •
40
- <a href="#quick-start">Quick start</a> •
41
- <a href="./examples">Examples</a> •
42
- <a href="#frameworks">Frameworks</a> •
43
- <a href="#star-history">Star history</a>
44
- </strong>
45
- </p>
29
+ ## Demo
46
30
 
47
- <p>If Pompelmi saves you from building upload security plumbing from scratch, give it a star. It helps the project grow and helps more Node.js teams find it.</p>
31
+ ![Pompelmi demo](assets/malware-detection-node-demo.gif)
48
32
 
49
- </div>
33
+ ## Install
50
34
 
51
- <p align="center">
52
- <img src="https://raw.githubusercontent.com/pompelmi/pompelmi/main/assets/readme-banner.png" alt="Pompelmi banner" width="100%">
53
- </p>
54
-
55
- ## Featured In
35
+ ```bash
36
+ npm install pompelmi
37
+ ```
56
38
 
57
- Picked up by developer newsletters, security media, and curated awesome lists.
39
+ Requires Node.js 18+.
58
40
 
59
- <p align="center">
60
- <a href="https://www.producthunt.com/products/pompelmi"><img alt="Featured on Product Hunt" src="https://img.shields.io/badge/featured-Product%20Hunt-da552f?style=for-the-badge&logo=producthunt&logoColor=white"></a>
61
- <a href="https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/"><img alt="Featured on Help Net Security" src="https://img.shields.io/badge/featured-Help%20Net%20Security-ff6b35?style=for-the-badge"></a>
62
- <a href="https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/"><img alt="Featured on Stack Overflow Blog" src="https://img.shields.io/badge/featured-Stack%20Overflow%20Blog-f58025?style=for-the-badge&logo=stackoverflow&logoColor=white"></a>
63
- <a href="https://nodeweekly.com/issues/594"><img alt="Featured in Node Weekly issue 594" src="https://img.shields.io/badge/featured-Node%20Weekly%20%23594-43853d?style=for-the-badge&logo=node.js&logoColor=white"></a>
64
- <a href="https://bytes.dev/archives/429"><img alt="Featured in Bytes issue 429" src="https://img.shields.io/badge/featured-Bytes%20%23429-111111?style=for-the-badge"></a>
65
- <a href="https://www.detectionengineering.net/p/det-eng-weekly-issue-124-the-defcon"><img alt="Featured in Detection Engineering Weekly issue 124" src="https://img.shields.io/badge/featured-Detection%20Engineering%20Weekly-2563eb?style=for-the-badge&logo=substack&logoColor=white"></a>
66
- </p>
41
+ ## Quick Start
67
42
 
68
- <p align="center">
69
- <a href="https://github.com/sorrycc/awesome-javascript"><img alt="Included in Awesome JavaScript" src="https://img.shields.io/badge/awesome-Awesome%20JavaScript-f7df1e?style=for-the-badge&logo=javascript&logoColor=black"></a>
70
- <a href="https://github.com/dzharii/awesome-typescript"><img alt="Included in Awesome TypeScript" src="https://img.shields.io/badge/awesome-Awesome%20TypeScript-3178c6?style=for-the-badge&logo=typescript&logoColor=white"></a>
71
- </p>
43
+ ```ts
44
+ import { scanBytes } from 'pompelmi';
72
45
 
73
- ## Why It Exists
46
+ const report = await scanBytes(file.buffer, {
47
+ ctx: {
48
+ filename: file.originalname,
49
+ mimeType: file.mimetype,
50
+ size: file.size,
51
+ },
52
+ });
74
53
 
75
- Your file upload endpoint is part of your attack surface.
54
+ if (!report.ok) {
55
+ return res.status(422).json({
56
+ error: 'Upload blocked',
57
+ verdict: report.verdict,
58
+ reasons: report.reasons,
59
+ });
60
+ }
61
+ ```
76
62
 
77
- Most upload handlers still trust filenames, extensions, or client-provided MIME types. That leaves room for renamed files, archive bombs, polyglots, active PDFs, and other risky payloads to land in storage before your app notices.
63
+ ## What Problem It Solves
78
64
 
79
- Without Pompelmi:
65
+ Upload endpoints are part of your attack surface. A renamed executable, a risky PDF, or a hostile archive can look harmless until it is stored, unpacked, served, or parsed by another system.
80
66
 
81
- `upload -> trust filename/MIME -> store -> parse or serve later`
67
+ Pompelmi adds checks at the upload boundary for:
82
68
 
83
- With Pompelmi:
69
+ - MIME spoofing and magic-byte mismatches
70
+ - Archive abuse such as ZIP bombs, traversal, and deep nesting
71
+ - Polyglot files and risky document structures
72
+ - Optional YARA-based signature matching
84
73
 
85
- `upload -> inspect bytes + structure -> allow | quarantine | reject -> store/process`
74
+ The goal is simple: inspect first, store later.
86
75
 
87
- Why teams choose it:
76
+ ## Why This Shape
88
77
 
89
- - In-process and local-first. No cloud API, no daemon, no data egress.
90
- - Built for the stuff attackers actually abuse: spoofed MIME, nested archives, ZIP bombs, traversal, polyglots, macro hints, and active documents.
91
- - Typed and composable APIs with `scanBytes`, `scanFile`, policy packs, hooks, and optional YARA.
92
- - Drop-in packages for Express, Next.js, Koa, NestJS, Fastify, CLI workflows, and React UI.
78
+ - Plain Markdown, readable in GitHub and in a terminal
79
+ - Fast path first: install, example, then deeper links
80
+ - Minimal top-level detail, with docs and examples for everything else
93
81
 
94
- ## Why People Star It
82
+ ## Ecosystem
95
83
 
96
- - It solves a real pain point fast: secure uploads are usually more dangerous and more annoying than they look.
97
- - It is easy to adopt: `npm install`, add a policy, block risky files before storage.
98
- - It stays privacy-first: no cloud dependency, no file egress, no extra scanning service to operate.
99
- - It feels production-minded: structured verdicts, clear reasons, adapters, examples, docs, and active release history.
84
+ - `pompelmi`
85
+ - `@pompelmi/express-middleware`
86
+ - `@pompelmi/koa-middleware`
87
+ - `@pompelmi/next-upload`
88
+ - `@pompelmi/nestjs-integration`
89
+ - `@pompelmi/fastify-plugin`
90
+ - `@pompelmi/ui-react`
91
+ - `@pompelmi/cli`
100
92
 
101
- ## Demo
93
+ ## Repository Layout
102
94
 
103
- <p align="center">
104
- <img src="https://raw.githubusercontent.com/pompelmi/pompelmi/main/assets/malware-detection-node-demo.gif" alt="Pompelmi demo showing a risky upload being blocked" width="920">
105
- </p>
95
+ - `src/` core library
96
+ - `packages/` framework adapters and supporting packages
97
+ - `examples/` runnable examples
98
+ - `tests/` test coverage
99
+ - `website/` documentation site
106
100
 
107
- ## Quick Start
101
+ ## Development
108
102
 
109
103
  ```bash
110
- npm install pompelmi
111
- ```
112
-
113
- ```ts
114
- import { scanBytes, STRICT_PUBLIC_UPLOAD } from 'pompelmi';
115
-
116
- const report = await scanBytes(file.buffer, {
117
- filename: file.originalname,
118
- mimeType: file.mimetype,
119
- policy: STRICT_PUBLIC_UPLOAD,
120
- failClosed: true,
121
- });
122
-
123
- if (report.verdict !== 'clean') {
124
- return res.status(422).json({
125
- error: 'Upload blocked',
126
- reasons: report.reasons,
127
- });
128
- }
104
+ pnpm install
105
+ pnpm test
106
+ pnpm build
129
107
  ```
130
108
 
131
- Start here next:
109
+ ## Links
132
110
 
133
- - [Getting started](https://pompelmi.github.io/pompelmi/getting-started/)
134
- - [Express guide](https://pompelmi.github.io/pompelmi/how-to/express/)
111
+ - [Documentation](https://pompelmi.github.io/pompelmi/)
135
112
  - [Examples](./examples)
136
- - [Threat model and architecture](https://pompelmi.github.io/pompelmi/explaination/architecture/)
137
-
138
- ## What It Checks
113
+ - [Contributing](./CONTRIBUTING.md)
114
+ - [Security](./SECURITY.md)
115
+ - [Roadmap](./ROADMAP.md)
139
116
 
140
- - Extension, size, and declared MIME policy checks.
141
- - Magic-byte validation for renamed or disguised files.
142
- - Archive protections for ZIP bombs, traversal, and nesting depth.
143
- - Heuristics for risky structures such as executables, polyglots, script-bearing documents, and macro hints.
144
- - Optional YARA matching when you need signature-based rules.
117
+ <!-- MENTIONS:START -->
145
118
 
146
- ## Frameworks
119
+ ## 🌟 Featured In
147
120
 
148
- | Use case | Package or guide |
149
- | --- | --- |
150
- | Core library | `pompelmi` |
151
- | Express | `@pompelmi/express-middleware` |
152
- | Next.js | `@pompelmi/next-upload` |
153
- | Koa | `@pompelmi/koa-middleware` |
154
- | NestJS | `@pompelmi/nestjs-integration` |
155
- | Fastify | `@pompelmi/fastify-plugin` |
156
- | React UI | `@pompelmi/ui-react` |
157
- | CLI | `@pompelmi/cli` |
121
+ *Last updated: March 20, 2026*
158
122
 
159
- ## Why Not Just MIME Checks, Cloud AV, or ClamAV?
123
+ ### 📋 Awesome Lists & Curated Collections
160
124
 
161
- | Approach | Where it helps | Where it falls short |
162
- | --- | --- | --- |
163
- | File extensions or MIME checks only | Cheap allowlists and quick policy enforcement | Renamed files and client-provided MIME values are easy to fake. |
164
- | DIY upload validation | Full control over your own rules | Easy to miss archive handling, polyglots, structured verdicts, and consistent fail-closed behavior. |
165
- | Cloud scanning APIs | Outsourced detection and managed infrastructure | Adds data egress, network latency, and a hard dependency on an external service. |
166
- | ClamAV or daemon-based setups | Familiar signature scanning and existing operations model | Adds process overhead and still benefits from an application-layer upload gate before storage. |
125
+ - [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript) — sorrycc
126
+ - [Awesome TypeScript](https://github.com/dzharii/awesome-typescript) — dzharii
167
127
 
168
- Pompelmi focuses on the upload gate itself. It can complement YARA or ClamAV. It is not presented as a full antivirus replacement.
128
+ ### 📰 Newsletters & Roundups
169
129
 
170
- ## Star History
130
+ - [The Overflow Issue 319: Dogfooding your SDLC](https://stackoverflow.blog/newsletter/issue-319-dogfooding-your-sdlc/) — Stack Overflow (2026-03-04)
131
+ - [Hottest cybersecurity open-source tools of the month: February 2026](https://www.helpnetsecurity.com/2026/02/26/hottest-cybersecurity-open-source-tools-of-the-month-february-2026/) — Help Net Security (2026-02-26)
132
+ - [Bytes #429](https://bytes.dev/archives/429) — Bytes (2025-10-03)
133
+ - [Node Weekly Issue 594](https://nodeweekly.com/issues/594) — Node Weekly (2025-09-30)
134
+ - [Det. Eng. Weekly Issue #124 - The DEFCON hangover is real](https://www.detectionengineering.net/p/det-eng-weekly-issue-124-the-defcon) — Detection Engineering (2025-08-13)
171
135
 
172
- If you want to follow the project as it grows, star the repo and keep an eye on releases.
136
+ ### 🔗 Other Mentions
173
137
 
174
- <p align="center">
175
- <a href="https://star-history.com/#pompelmi/pompelmi&Date">
176
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=pompelmi/pompelmi&type=Date">
177
- </a>
178
- </p>
138
+ - [Defense against uploads: Q&A with OSS file scanner, pompelmi](https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/) — Stack Overflow (2026-02-23)
139
+ - [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 (2026-02-02)
179
140
 
180
- ## Community
181
141
 
182
- - [Contributing guide](./CONTRIBUTING.md)
183
- - [Roadmap](./ROADMAP.md)
184
- - [GitHub Discussions](https://github.com/pompelmi/pompelmi/discussions)
185
- - [GitHub Issues](https://github.com/pompelmi/pompelmi/issues)
186
- - [Changelog](./CHANGELOG.md)
187
- - [Security policy](./SECURITY.md)
142
+ *Found 9 mentions. To update, run `npm run mentions:update`.*
188
143
 
189
- Questions, docs fixes, examples, tests, and real-world integration feedback are all useful here.
144
+ <!-- MENTIONS:END -->
190
145
 
191
146
  ## License
192
147
 
193
- MIT. See [LICENSE](./LICENSE). Also: [Docs](https://pompelmi.github.io/pompelmi/), [GitHub](https://github.com/pompelmi/pompelmi), [npm](https://www.npmjs.com/package/pompelmi).
148
+ [MIT](./LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pompelmi",
3
- "version": "0.34.4",
3
+ "version": "0.34.6",
4
4
  "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.",
5
5
  "main": "./dist/pompelmi.cjs",
6
6
  "module": "./dist/pompelmi.esm.js",