pompelmi 0.35.3 → 0.35.4

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 +87 -88
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,54 +1,65 @@
1
1
  <div align="center">
2
- <img src="./assets/logo.svg" alt="Pompelmi logo" width="144" />
2
+ <img src="./assets/logo.svg" alt="Pompelmi logo" width="120" />
3
3
 
4
4
  <h1>Pompelmi</h1>
5
5
 
6
- <p><strong>Route-level upload security for Node.js.</strong></p>
7
-
8
- <p>Inspect untrusted uploads before storage.</p>
6
+ <p><strong>Secure file uploads in Node.js before storage.</strong></p>
9
7
 
10
8
  <p>
11
- MIME and extension spoofing · archive abuse · risky document and binary
12
- signals · optional YARA
9
+ Open-source route-level upload security for Node.js teams that need to
10
+ inspect untrusted files before disk, object storage, previews, or
11
+ downstream parsers.
13
12
  </p>
14
13
 
15
14
  <p><code>clean</code> · <code>suspicious</code> · <code>malicious</code></p>
16
15
 
17
16
  <p>
18
- <sub>Express · Next.js · NestJS · Fastify · Koa · Nuxt/Nitro · S3 quarantine flows · CI/CD</sub>
17
+ MIME spoofing · risky archives · document and binary signals · optional
18
+ YARA
19
19
  </p>
20
20
 
21
- <p><sub>Open-source core · MIT · Node.js 18+</sub></p>
21
+ <p>
22
+ <sub>Express · Next.js · NestJS · Fastify · Koa · Nuxt/Nitro · S3 quarantine flows · CI/CD</sub>
23
+ </p>
22
24
 
23
25
  <p>
24
26
  <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi" /></a>
25
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?label=ci" /></a>
26
28
  <a href="https://codecov.io/gh/pompelmi/pompelmi"><img alt="codecov" src="https://codecov.io/gh/pompelmi/pompelmi/graph/badge.svg" /></a>
27
29
  <a href="https://github.com/pompelmi/pompelmi/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social" /></a>
28
- <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm weekly downloads" src="https://img.shields.io/npm/dw/pompelmi" /></a>
29
- <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm monthly downloads" src="https://img.shields.io/npm/dm/pompelmi" /></a>
30
30
  </p>
31
31
 
32
32
  <p>
33
- <a href="https://pompelmi.github.io/pompelmi/getting-started/"><strong>Getting started</strong></a>
33
+ <a href="https://pompelmi.app/"><strong>Docs</strong></a>
34
+ ·
35
+ <a href="https://pompelmi.app/getting-started/"><strong>Getting started</strong></a>
34
36
  ·
35
- <a href="https://pompelmi.github.io/pompelmi/#browser-preview"><strong>Browser preview</strong></a>
37
+ <a href="https://pompelmi.app/#browser-preview"><strong>Browser preview</strong></a>
36
38
  ·
37
39
  <a href="./examples/demo"><strong>Express demo</strong></a>
38
40
  ·
39
41
  <a href="./examples/README.md"><strong>Examples</strong></a>
40
42
  </p>
43
+
44
+ <p><sub>Node.js 18+ · MIT</sub></p>
41
45
  </div>
42
46
 
43
47
  <p align="center">
44
- Mentioned by <a href="https://nodeweekly.com/issues/594">Node Weekly</a>,
48
+ <strong>Mentioned by</strong>
49
+ <a href="https://nodeweekly.com/issues/594">Node Weekly</a>,
45
50
  <a href="https://stackoverflow.blog/2026/02/23/defense-against-uploads-oss-file-scanner-pompelmi/">Stack Overflow</a>,
46
51
  <a href="https://www.helpnetsecurity.com/2026/02/02/pompelmi-open-source-secure-file-upload-scanning-node-js/">Help Net Security</a>,
47
52
  <a href="https://github.com/sorrycc/awesome-javascript">Awesome JavaScript</a>,
48
53
  and
49
- <a href="https://github.com/dzharii/awesome-typescript">Awesome TypeScript</a>.
54
+ <a href="https://github.com/dzharii/awesome-typescript">Awesome TypeScript</a>
50
55
  </p>
51
56
 
57
+ <p align="center">
58
+ <sub>If you want upload security to start at the route boundary instead of after storage, consider starring the repo.</sub>
59
+ </p>
60
+
61
+ > Upload endpoints are part of your attack surface. Pompelmi helps Node.js teams scan files before storage and make the decision while the route still has context: accept, quarantine, or reject.
62
+
52
63
  ## Quick Start
53
64
 
54
65
  Install the core package:
@@ -57,7 +68,7 @@ Install the core package:
57
68
  npm install pompelmi
58
69
  ```
59
70
 
60
- Minimal route-level example:
71
+ This is the core pattern: inspect bytes, get a verdict, and only store clean files.
61
72
 
62
73
  ```ts
63
74
  import { scanBytes, STRICT_PUBLIC_UPLOAD } from 'pompelmi';
@@ -80,104 +91,92 @@ if (report.verdict !== 'clean') {
80
91
  return res.status(200).json({ verdict: report.verdict });
81
92
  ```
82
93
 
83
- 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).
84
-
85
- If Pompelmi matches how you want upload security to work, star the repo so more Node.js teams can find it.
94
+ Start with [Getting started](https://pompelmi.app/getting-started/) for a local scan in under a minute, open the [browser preview](https://pompelmi.app/#browser-preview) to inspect the verdict flow without sending files anywhere, or run the minimal [Express demo](./examples/demo).
86
95
 
87
- ## Why It Exists
96
+ ## Why teams use Pompelmi
88
97
 
89
- 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.
98
+ - File upload endpoints are not just form validation. Files can become risky after storage, extraction, rendering, or downstream parsing.
99
+ - Pompelmi keeps the first trust decision inside the application path, where the route still knows the file class, trust level, storage path, and failure mode.
100
+ - It gives Node.js teams a practical way to build secure file uploads with route-level decisions instead of bolting checks on after persistence.
90
101
 
91
- Pompelmi keeps the first decision inside the application path, where the route still knows the file class, trust level, storage path, and failure mode.
102
+ ## What it checks
92
103
 
93
- ## What It Checks
104
+ - MIME sniffing, magic-byte validation, and extension mismatch detection
105
+ - Risky archives such as ZIP bombs, traversal attempts, deep nesting, and entry-count abuse
106
+ - Risky document and binary signals such as PDF actions, Office macro hints, PE headers, and polyglot files
107
+ - Optional YARA-based matches when you want malware scanning uploads as part of the flow
108
+ - Verdicts and reasons you can use for fail-closed routes, quarantine flows, and auditability
94
109
 
95
- - MIME sniffing, magic-byte validation, and extension allowlists
96
- - risky archive structures such as traversal, deep nesting, entry-count abuse, and ZIP bomb-style expansion
97
- - suspicious document and binary signals such as risky PDF actions, Office macro hints, PE headers, and polyglot files
98
- - optional YARA or other scanner matches
99
- - route-level verdicts that support reject, quarantine, or promote workflows
110
+ ## Where it fits in the upload pipeline
100
111
 
101
- ## Where It Fits
112
+ 1. Receive the upload into memory or an isolated staging or quarantine area.
113
+ 2. Scan the bytes with a route policy.
114
+ 3. Act on the verdict: `clean`, `suspicious`, or `malicious`.
115
+ 4. Persist, quarantine, or reject based on the route's rules.
102
116
 
103
- - public or semi-trusted upload endpoints that should inspect first and store later
104
- - memory-backed multipart routes in Express, Next.js, NestJS, Fastify, and Koa
105
- - quarantine and promotion workflows for S3 or other object storage
106
- - document, image, and archive routes that need different policies
107
- - CI/CD or internal artifact scanning before promotion
117
+ That inspect-first, store-later shape is where Pompelmi is strongest.
108
118
 
109
- ## Why Not Just X?
119
+ ## What it is and isn't
110
120
 
111
121
  | Approach | Useful for | What it misses |
112
122
  | --- | --- | --- |
113
- | Browser MIME and extension checks | Fast client-side hints and UX feedback | Filenames and client-reported MIME are easy to spoof |
114
- | 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 |
115
- | Antivirus-only thinking | Known malicious matches and signature-based detection | Route context, spoofing checks, storage decisions, and non-signature risk signals |
116
- | 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 |
117
-
118
- ## Integrations
119
-
120
- - Express: [Docs](https://pompelmi.github.io/pompelmi/how-to/express/) · [Minimal example](./examples/express-minimal) · [Demo](./examples/demo)
121
- - Next.js: [Docs](https://pompelmi.github.io/pompelmi/how-to/nextjs/) · [Example](./examples/next-app-router)
122
- - NestJS: [Docs](https://pompelmi.github.io/pompelmi/how-to/nestjs/) · [Example app](./examples/nestjs-app)
123
- - Fastify: [Docs](https://pompelmi.github.io/pompelmi/how-to/fastify/) · [Package](./packages/fastify-plugin)
124
- - Koa: [Docs](https://pompelmi.github.io/pompelmi/how-to/koa/) · [Package](./packages/koa-middleware)
125
- - Nuxt/Nitro: [Docs](https://pompelmi.github.io/pompelmi/how-to/nuxt-nitro/)
126
- - 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/)
127
- - 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/)
128
-
129
- ## Demo, Preview, and Examples
123
+ | Browser MIME and extension checks | Fast client-side hints and UX feedback | Client MIME and filenames are easy to spoof |
124
+ | File-type or magic-byte validation only | Confirming a file looks like the claimed type | Archive abuse, risky internal structure, and route policy decisions |
125
+ | Antivirus or YARA only | Known malicious matches and signature-style detection | Route context, spoofing checks, and before-storage handling |
126
+ | Pompelmi at the upload route | Node.js file upload security, scan files before storage, and verdict-driven workflow decisions | It is not a full antivirus replacement on its own |
127
+
128
+ ## Supported frameworks and workflows
129
+
130
+ | Stack or workflow | Links |
131
+ | --- | --- |
132
+ | Express | [Docs](https://pompelmi.app/how-to/express/) · [Minimal example](./examples/express-minimal) · [Demo](./examples/demo) |
133
+ | Next.js | [Docs](https://pompelmi.app/how-to/nextjs/) · [Example](./examples/next-app-router) · [Package](./packages/next-upload) |
134
+ | NestJS | [Docs](https://pompelmi.app/how-to/nestjs/) · [Package](./packages/nestjs) · [Example app](./examples/nestjs-app) |
135
+ | Fastify | [Docs](https://pompelmi.app/how-to/fastify/) · [Package](./packages/fastify-plugin) |
136
+ | Koa | [Docs](https://pompelmi.app/how-to/koa/) · [Package](./packages/koa-middleware) |
137
+ | Nuxt/Nitro | [Docs](https://pompelmi.app/how-to/nuxt-nitro/) · [Example](./examples/nuxt-nitro) |
138
+ | S3 / object storage | [Tutorial](https://pompelmi.app/tutorials/secure-s3-presigned-uploads-with-malware-scanning/) · [Use case](https://pompelmi.app/use-cases/object-storage-promotion-workflows/) |
139
+ | CI/CD | [Use case](https://pompelmi.app/use-cases/cicd-artifact-scanning/) · [Blog](https://pompelmi.app/blog/cicd-scan-build-artifacts/) |
140
+
141
+ ## Demo, preview, and examples
130
142
 
131
143
  ![Pompelmi upload security demo](assets/malware-detection-node-demo.gif)
132
144
 
133
- - [Browser preview](https://pompelmi.github.io/pompelmi/#browser-preview) for a fast local evaluation of the verdict UX
134
- - [Demo](./examples/demo) for a tiny Express upload gate that returns `clean`, `suspicious`, or `malicious` before storage
135
- - [Examples index](./examples/README.md) for framework-specific and production-oriented examples
136
-
137
- ## Docs
145
+ - [Browser preview](https://pompelmi.app/#browser-preview) for a fast local look at the verdict UX without uploading files anywhere
146
+ - [Express demo](./examples/demo) for a tiny upload gate that returns `clean`, `suspicious`, or `malicious` before storage
147
+ - [Examples index](./examples/README.md) for framework-specific and production-oriented patterns
148
+ - [Docs home](https://pompelmi.app/) for guides, comparisons, use cases, and tutorials
138
149
 
139
- - [Docs home](https://pompelmi.github.io/pompelmi/)
140
- - [Getting started](https://pompelmi.github.io/pompelmi/getting-started/)
141
- - [Use cases](https://pompelmi.github.io/pompelmi/use-cases/)
142
- - [Comparisons](https://pompelmi.github.io/pompelmi/comparisons/)
143
- - [Tutorials](https://pompelmi.github.io/pompelmi/tutorials/)
144
- - [Featured in](https://pompelmi.github.io/pompelmi/featured-in/)
145
- - [Translations](https://pompelmi.github.io/pompelmi/translations/)
150
+ ## Why star this repo
146
151
 
147
- ## Enterprise and Commercial Support
148
-
149
- 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/).
152
+ Pompelmi is focused on a real gap in most Node.js stacks: secure file uploads that make a decision before storage, not after. If that matches how you want upload security to work, star the repo to follow the project and help more teams discover the inspect-before-storage model.
150
153
 
151
154
  <!-- MENTIONS:START -->
152
155
 
153
- ## Featured In
154
-
155
- Full page: [pompelmi.github.io/pompelmi/featured-in](https://pompelmi.github.io/pompelmi/featured-in/)
156
-
157
- *Last updated: March 20, 2026*
156
+ ## Mentioned by
158
157
 
159
- ### Awesome Lists & Curated Collections
158
+ - [Node Weekly](https://nodeweekly.com/issues/594)
159
+ - [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
160
+ - [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
161
+ - [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript)
162
+ - [Awesome TypeScript](https://github.com/dzharii/awesome-typescript)
163
+ - [See all mentions](https://pompelmi.app/featured-in/)
160
164
 
161
- - [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript) — sorrycc
162
- - [Awesome TypeScript](https://github.com/dzharii/awesome-typescript) — dzharii
163
-
164
- ### Newsletters & Roundups
165
-
166
- - [The Overflow Issue 319: Dogfooding your SDLC](https://stackoverflow.blog/newsletter/issue-319-dogfooding-your-sdlc/) — Stack Overflow (2026-03-04)
167
- - [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)
168
- - [Bytes #429](https://bytes.dev/archives/429) — Bytes (2025-10-03)
169
- - [Node Weekly Issue 594](https://nodeweekly.com/issues/594) — Node Weekly (2025-09-30)
170
- - [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
-
172
- ### Other Mentions
165
+ <!-- MENTIONS:END -->
173
166
 
174
- - [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)
175
- - [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)
167
+ ## Docs
176
168
 
169
+ - [Getting started](https://pompelmi.app/getting-started/)
170
+ - [Use cases](https://pompelmi.app/use-cases/)
171
+ - [Comparisons](https://pompelmi.app/comparisons/)
172
+ - [Tutorials](https://pompelmi.app/tutorials/)
173
+ - [Browser preview](https://pompelmi.app/#browser-preview)
174
+ - [Featured in](https://pompelmi.app/featured-in/)
175
+ - [Translations](https://pompelmi.app/translations/)
177
176
 
178
- *Found 9 mentions. To update, run `npm run mentions:update`.*
177
+ ## Commercial support
179
178
 
180
- <!-- MENTIONS:END -->
179
+ 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.app/enterprise/).
181
180
 
182
181
  ## Project
183
182
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pompelmi",
3
- "version": "0.35.3",
3
+ "version": "0.35.4",
4
4
  "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.",
5
5
  "main": "./dist/pompelmi.cjs",
6
6
  "module": "./dist/pompelmi.esm.js",