pompelmi 0.13.0-dev.20 → 0.13.0-dev.22
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.
- package/README.md +63 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
<img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white">
|
|
17
17
|
<img alt="types" src="https://img.shields.io/badge/types-TypeScript-3178C6?logo=typescript&logoColor=white">
|
|
18
18
|
<a href="https://github.com/pompelmi/pompelmi/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/pompelmi"></a>
|
|
19
|
-
|
|
19
|
+
<a href="https://app.codecov.io/gh/pompelmi/pompelmi"><img alt="coverage (core)" src="https://img.shields.io/codecov/c/github/pompelmi/pompelmi?branch=main&flag=core&label=coverage%20(core)&cacheSeconds=300"/></a>
|
|
20
20
|
<a href="https://github.com/pompelmi/pompelmi/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social"></a>
|
|
21
21
|
<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>
|
|
22
22
|
<a href="https://github.com/pompelmi/pompelmi/issues"><img alt="open issues" src="https://img.shields.io/github/issues/pompelmi/pompelmi"></a>
|
|
@@ -40,6 +40,16 @@
|
|
|
40
40
|
|
|
41
41
|
---
|
|
42
42
|
|
|
43
|
+
## Overview
|
|
44
|
+
|
|
45
|
+
**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.
|
|
46
|
+
|
|
47
|
+
- **Private by design** — no outbound calls; bytes never leave your process
|
|
48
|
+
- **Composable scanners** — mix heuristics + signatures; set `stopOn` and timeouts
|
|
49
|
+
- **ZIP hardening** — traversal/bomb guards, polyglot & macro hints
|
|
50
|
+
- **Drop-in adapters** — Express, Koa, Fastify, Next.js
|
|
51
|
+
- **Typed & tiny** — modern TS, minimal surface
|
|
52
|
+
|
|
43
53
|
## Highlights
|
|
44
54
|
|
|
45
55
|
- **Block risky uploads early** — classify uploads as _clean_, _suspicious_, or _malicious_ and stop them at the edge.
|
|
@@ -220,10 +230,18 @@ Use the adapter that matches your web framework. All adapters share the same pol
|
|
|
220
230
|
## Diagrams
|
|
221
231
|
|
|
222
232
|
### Upload scanning flow
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
233
|
+
```mermaid
|
|
234
|
+
flowchart TD
|
|
235
|
+
A["Client uploads file(s)"] --> B["Web App Route"]
|
|
236
|
+
B --> C{"Pre-filters<br/>(ext, size, MIME)"}
|
|
237
|
+
C -- fail --> X["HTTP 4xx"]
|
|
238
|
+
C -- pass --> D{"Is ZIP?"}
|
|
239
|
+
D -- yes --> E["Iterate entries<br/>(limits & scan)"]
|
|
240
|
+
E --> F{"Verdict?"}
|
|
241
|
+
D -- no --> F{"Scan bytes"}
|
|
242
|
+
F -- malicious/suspicious --> Y["HTTP 422 blocked"]
|
|
243
|
+
F -- clean --> Z["HTTP 200 ok + results"]
|
|
244
|
+
```
|
|
227
245
|
<details>
|
|
228
246
|
<summary>Mermaid source</summary>
|
|
229
247
|
|
|
@@ -242,10 +260,24 @@ flowchart TD
|
|
|
242
260
|
</details>
|
|
243
261
|
|
|
244
262
|
### Sequence (App ↔ pompelmi ↔ YARA)
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
263
|
+
```mermaid
|
|
264
|
+
sequenceDiagram
|
|
265
|
+
participant U as User
|
|
266
|
+
participant A as App Route (/upload)
|
|
267
|
+
participant P as pompelmi (adapter)
|
|
268
|
+
participant Y as YARA engine
|
|
248
269
|
|
|
270
|
+
U->>A: POST multipart/form-data
|
|
271
|
+
A->>P: guard(files, policies)
|
|
272
|
+
P->>P: MIME sniff + size + ext checks
|
|
273
|
+
alt ZIP archive
|
|
274
|
+
P->>P: unpack entries with limits
|
|
275
|
+
end
|
|
276
|
+
P->>Y: scan(bytes)
|
|
277
|
+
Y-->>P: matches[]
|
|
278
|
+
P-->>A: verdict (clean/suspicious/malicious)
|
|
279
|
+
A-->>U: 200 or 4xx/422 with reason
|
|
280
|
+
```
|
|
249
281
|
<details>
|
|
250
282
|
<summary>Mermaid source</summary>
|
|
251
283
|
|
|
@@ -270,10 +302,28 @@ sequenceDiagram
|
|
|
270
302
|
</details>
|
|
271
303
|
|
|
272
304
|
### Components (monorepo)
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
305
|
+
```mermaid
|
|
306
|
+
flowchart LR
|
|
307
|
+
subgraph Repo
|
|
308
|
+
core["pompelmi (core)"]
|
|
309
|
+
express["@pompelmi/express-middleware"]
|
|
310
|
+
koa["@pompelmi/koa-middleware"]
|
|
311
|
+
next["@pompelmi/next-upload"]
|
|
312
|
+
fastify(("fastify-plugin · planned"))
|
|
313
|
+
nest(("nestjs · planned"))
|
|
314
|
+
remix(("remix · planned"))
|
|
315
|
+
hapi(("hapi-plugin · planned"))
|
|
316
|
+
svelte(("sveltekit · planned"))
|
|
317
|
+
end
|
|
318
|
+
core --> express
|
|
319
|
+
core --> koa
|
|
320
|
+
core --> next
|
|
321
|
+
core -.-> fastify
|
|
322
|
+
core -.-> nest
|
|
323
|
+
core -.-> remix
|
|
324
|
+
core -.-> hapi
|
|
325
|
+
core -.-> svelte
|
|
326
|
+
```
|
|
277
327
|
<details>
|
|
278
328
|
<summary>Mermaid source</summary>
|
|
279
329
|
|
|
@@ -417,7 +467,7 @@ The badge tracks the **core library** (`src/**`). Adapters and engines are repor
|
|
|
417
467
|
If you integrate Codecov in CI, upload `coverage/lcov.info` and you can use this Shields badge (cached 5 minutes):
|
|
418
468
|
|
|
419
469
|
```md
|
|
420
|
-
[&flag=core&cacheSeconds=300)](https://codecov.io/gh/pompelmi/pompelmi)
|
|
421
471
|
```
|
|
422
472
|
|
|
423
473
|
## Contributing
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pompelmi",
|
|
3
|
-
"version": "0.13.0-dev.
|
|
3
|
+
"version": "0.13.0-dev.22",
|
|
4
4
|
"description": "RFI-safe file uploads for Node.js — Express/Koa/Next.js middleware with deep ZIP inspection, MIME/size checks, and optional YARA scanning.",
|
|
5
5
|
"main": "dist/pompelmi.cjs.js",
|
|
6
6
|
"module": "dist/pompelmi.esm.js",
|