pompelmi 0.34.2 → 0.34.5

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 +107 -82
  2. package/package.json +17 -35
package/README.md CHANGED
@@ -1,119 +1,144 @@
1
- ![Pompelmi banner](./assets/readme-banner.png)
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>
24
+
25
+ Pompelmi inspects untrusted files before storage and helps you decide whether to allow, reject, or quarantine them before they reach downstream systems.
26
+
27
+ It is built for upload endpoints that cannot rely on filenames, extensions, or client-provided MIME types alone.
28
+
29
+ ## Install
2
30
 
3
- # Pompelmi
31
+ ```bash
32
+ npm install pompelmi
33
+ ```
4
34
 
5
- [![GitHub stars](https://img.shields.io/github/stars/pompelmi/pompelmi?style=flat-square&logo=github)](https://github.com/pompelmi/pompelmi/stargazers)
6
- [![npm version](https://img.shields.io/npm/v/pompelmi?label=version&logo=npm)](https://www.npmjs.com/package/pompelmi)
7
- [![CI](https://img.shields.io/github/actions/workflow/status/pompelmi/pompelmi/ci.yml?branch=main&label=CI&logo=github)](https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml)
35
+ Requires Node.js 18+.
8
36
 
9
- In-process file upload security for Node.js.
37
+ ## Quick Start
10
38
 
11
- Your file upload endpoint is part of your attack surface.
39
+ ```ts
40
+ import { scanBytes } from 'pompelmi';
12
41
 
13
- Pompelmi is an open-source Node.js library that scans and blocks risky uploads before they hit storage or downstream processing. It runs in-process, with no cloud API, no daemon, and no required data egress.
42
+ const report = await scanBytes(file.buffer, {
43
+ ctx: {
44
+ filename: file.originalname,
45
+ mimeType: file.mimetype,
46
+ size: file.size,
47
+ },
48
+ });
14
49
 
15
- Works with Express, Next.js, NestJS, Fastify, and Koa. The MIT-licensed core is the primary path in this repo.
50
+ if (!report.ok) {
51
+ return res.status(422).json({
52
+ error: 'Upload blocked',
53
+ verdict: report.verdict,
54
+ reasons: report.reasons,
55
+ });
56
+ }
57
+ ```
16
58
 
17
- ## Why this matters
59
+ ## What Problem It Solves
18
60
 
19
- Most upload handlers stop at extension checks or client-provided MIME types. That leaves gaps for spoofed files, archive bombs, polyglots, and script-bearing documents.
61
+ 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.
20
62
 
21
- Without Pompelmi:
63
+ Pompelmi adds checks at the upload boundary for:
22
64
 
23
- `upload -> trust filename/MIME -> store -> parse or serve later`
65
+ - MIME spoofing and magic-byte mismatches
66
+ - Archive abuse such as ZIP bombs, traversal, and deep nesting
67
+ - Polyglot files and risky document structures
68
+ - Optional YARA-based signature matching
24
69
 
25
- With Pompelmi:
70
+ The goal is simple: inspect first, store later.
26
71
 
27
- `upload -> inspect bytes + structure -> allow | quarantine | reject -> store/process`
72
+ ## Why This Shape
28
73
 
29
- ## Key protections
74
+ - Plain Markdown, readable in GitHub and in a terminal
75
+ - Fast path first: install, example, then deeper links
76
+ - Minimal top-level detail, with docs and examples for everything else
30
77
 
31
- - Extension, size, and declared MIME policy checks.
32
- - Magic-byte validation for renamed or disguised files.
33
- - Archive controls for ZIP bombs, traversal, and nesting depth.
34
- - Heuristics for risky structures such as executables, polyglots, and script-bearing documents.
35
- - Optional YARA matching when you need signature-based rules.
78
+ ## Ecosystem
36
79
 
37
- ## Quick start
80
+ - `pompelmi`
81
+ - `@pompelmi/express-middleware`
82
+ - `@pompelmi/koa-middleware`
83
+ - `@pompelmi/next-upload`
84
+ - `@pompelmi/nestjs-integration`
85
+ - `@pompelmi/fastify-plugin`
86
+ - `@pompelmi/ui-react`
87
+ - `@pompelmi/cli`
38
88
 
39
- ```bash
40
- npm install pompelmi
41
- ```
89
+ ## Repository Layout
42
90
 
43
- ```ts
44
- import { scanBytes, STRICT_PUBLIC_UPLOAD } from 'pompelmi';
91
+ - `src/` core library
92
+ - `packages/` framework adapters and supporting packages
93
+ - `examples/` runnable examples
94
+ - `tests/` test coverage
95
+ - `website/` documentation site
45
96
 
46
- const report = await scanBytes(file.buffer, {
47
- filename: file.originalname,
48
- mimeType: file.mimetype,
49
- policy: STRICT_PUBLIC_UPLOAD,
50
- failClosed: true,
51
- });
97
+ ## Development
52
98
 
53
- if (report.verdict !== 'clean') {
54
- return res.status(422).json({ error: 'Upload blocked', reasons: report.reasons });
55
- }
99
+ ```bash
100
+ pnpm install
101
+ pnpm test
102
+ pnpm build
56
103
  ```
57
104
 
58
- Next steps:
59
-
60
- - [Getting started](https://pompelmi.github.io/pompelmi/getting-started/)
61
- - [Framework guides](https://pompelmi.github.io/pompelmi/how-to/express/)
62
- - [Threat model and architecture](https://pompelmi.github.io/pompelmi/explaination/architecture/)
63
-
64
- ## Framework support
65
-
66
- | Framework | Package or guide |
67
- | --- | --- |
68
- | Express | `@pompelmi/express-middleware` |
69
- | Next.js | `@pompelmi/next-upload` |
70
- | NestJS | `@pompelmi/nestjs-integration` |
71
- | Koa | `@pompelmi/koa-middleware` |
72
- | Fastify | `@pompelmi/fastify-plugin` |
73
- | Nuxt/Nitro | guide in docs |
74
-
75
- ## Trust / production readiness
76
-
77
- - MIT-licensed core, typed APIs, framework adapters, and composable policy packs.
78
- - Structured verdicts, reasons, and rule matches for logging, quarantine, and review flows.
79
- - Public docs, examples, changelog, tests, and a security disclosure policy.
80
- - Local-first deployment model with no required cloud scanning dependency.
81
- - Built as a defense-in-depth upload gate, not a full antivirus replacement.
82
-
83
- Start here:
84
-
85
- - [Production readiness](https://pompelmi.github.io/pompelmi/production-readiness/)
86
- - [Threat model and architecture](https://pompelmi.github.io/pompelmi/explaination/architecture/)
87
- - [Examples directory](./examples)
88
- - [Security policy](./SECURITY.md)
89
- - [Tests](./tests)
105
+ ## Links
90
106
 
91
- ## FAQ
107
+ - [Documentation](https://pompelmi.github.io/pompelmi/)
108
+ - [Examples](./examples)
109
+ - [Contributing](./CONTRIBUTING.md)
110
+ - [Security](./SECURITY.md)
111
+ - [Roadmap](./ROADMAP.md)
92
112
 
93
- ### Does Pompelmi send files to a cloud API?
113
+ <!-- MENTIONS:START -->
94
114
 
95
- No. Scanning runs in-process by default. File bytes do not need to leave your infrastructure.
115
+ ## 🌟 Featured In
96
116
 
97
- ### Does it require ClamAV, a sidecar, or another daemon?
117
+ *Last updated: March 20, 2026*
98
118
 
99
- No. Built-in heuristics work without a daemon. ClamAV and YARA integrations are optional.
119
+ ### 📋 Awesome Lists & Curated Collections
100
120
 
101
- ### What does it help block?
121
+ - [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript) — sorrycc
122
+ - [Awesome TypeScript](https://github.com/dzharii/awesome-typescript) — dzharii
102
123
 
103
- It adds a layered upload gate before storage or downstream processing. That helps catch spoofed files, archive bombs, polyglots, and common risky document structures.
124
+ ### 📰 Newsletters & Roundups
104
125
 
105
- ### Is this a complete antivirus replacement?
126
+ - [The Overflow Issue 319: Dogfooding your SDLC](https://stackoverflow.blog/newsletter/issue-319-dogfooding-your-sdlc/) — Stack Overflow (2026-03-04)
127
+ - [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)
128
+ - [Bytes #429](https://bytes.dev/archives/429) — Bytes (2025-10-03)
129
+ - [Node Weekly Issue 594](https://nodeweekly.com/issues/594) — Node Weekly (2025-09-30)
130
+ - [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)
106
131
 
107
- No. Pompelmi is an upload security layer and risk-reduction control. It should sit inside a broader defense-in-depth design.
132
+ ### 🔗 Other Mentions
108
133
 
109
- ### Can it help in privacy-sensitive or regulated environments?
134
+ - [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)
135
+ - [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)
110
136
 
111
- It can support internal control objectives by reducing upload risk and producing structured scan outcomes. It is not itself a compliance certification.
112
137
 
113
- ## Commercial / enterprise
138
+ *Found 9 mentions. To update, run `npm run mentions:update`.*
114
139
 
115
- Commercial support and enterprise options are available for teams that need rollout help, advanced auditability, or additional operational features. The open-source MIT core remains the default path. See [Support options](https://pompelmi.github.io/pompelmi/support/) and [`@pompelmi/enterprise`](https://pompelmi.github.io/pompelmi/enterprise/).
140
+ <!-- MENTIONS:END -->
116
141
 
117
142
  ## License
118
143
 
119
- MIT. See [LICENSE](./LICENSE). Also: [Docs](https://pompelmi.github.io/pompelmi/), [GitHub](https://github.com/pompelmi/pompelmi), [npm](https://www.npmjs.com/package/pompelmi).
144
+ [MIT](./LICENSE)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pompelmi",
3
- "version": "0.34.2",
4
- "description": "In-process file upload security for Node.js — no cloud API, no daemon, no data egress. TypeScript-first library with Express, Next.js, NestJS, Fastify, Koa, and Nuxt/Nitro adapters. Features magic-byte MIME validation, ZIP bomb protection, YARA integration, and layered heuristic scanning. Built for privacy-sensitive and self-hosted environments.",
3
+ "version": "0.34.5",
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",
7
7
  "type": "module",
@@ -215,48 +215,30 @@
215
215
  "CHANGELOG*"
216
216
  ],
217
217
  "keywords": [
218
- "malware-scanner",
219
- "file-upload-security",
220
218
  "secure-file-upload",
219
+ "file-upload-security",
221
220
  "upload-security",
222
- "virus-scanner",
223
- "antivirus",
224
- "malware-detection",
225
- "threat-detection",
226
- "security-scanner",
227
- "file-scanner",
221
+ "upload-scanning",
228
222
  "file-scanning",
223
+ "file-validation",
224
+ "malware-scanner",
225
+ "mime-sniffing",
226
+ "magic-bytes",
227
+ "archive-security",
228
+ "zip-bomb-protection",
229
229
  "yara",
230
230
  "yara-rules",
231
- "zip-bomb-protection",
232
- "express-middleware",
233
- "koa-middleware",
234
- "fastify-plugin",
235
- "nextjs",
236
- "next-js",
237
- "nestjs",
238
- "nuxt",
231
+ "local-first-security",
232
+ "self-hosted-security",
239
233
  "nodejs-security",
240
- "typescript-security",
241
- "file-validation",
242
- "upload-sanitization",
243
- "mime-type-validation",
244
- "magic-bytes",
245
- "security",
246
- "cybersecurity",
247
- "devsecops",
248
- "gdpr-compliance",
249
- "hipaa-compliance",
250
- "privacy-first",
251
- "in-process-scanning",
252
- "zero-cloud",
253
- "self-hosted",
254
- "node",
255
- "nodejs",
256
234
  "typescript",
235
+ "nodejs",
257
236
  "express",
237
+ "nextjs",
238
+ "nestjs",
239
+ "fastify",
258
240
  "koa",
259
- "fastify"
241
+ "nuxt"
260
242
  ],
261
243
  "directories": {
262
244
  "example": "examples"