pompelmi 0.35.5 → 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node:*)",
+      "Bash(echo \"EXIT:$?\")",
+      "Bash(echo \"EXIT_CODE:$?\")",
+      "Bash(tee /tmp/pompelmi_test_out.txt)",
+      "Bash(echo \"done: $?\")",
+      "Bash(ls /Users/tommy/pompelmi/pompelmi/*.md)",
+      "Bash(ls /Users/tommy/pompelmi/pompelmi/LICENSE*)",
+      "WebSearch",
+      "WebFetch(domain:pompelmi.app)",
+      "WebFetch(domain:news.ycombinator.com)",
+      "WebFetch(domain:dev.to)",
+      "WebFetch(domain:socket.dev)",
+      "WebFetch(domain:helpnetsecurity.com)",
+      "WebFetch(domain:nodeweekly.com)",
+      "WebFetch(domain:bytes.dev)",
+      "WebFetch(domain:www.helpnetsecurity.com)",
+      "WebFetch(domain:www.enveil.com)",
+      "WebFetch(domain:img.helpnetsecurity.com)",
+      "WebFetch(domain:logo.clearbit.com)",
+      "WebFetch(domain:cdn.brandfetch.io)",
+      "WebFetch(domain:cooperpress.com)",
+      "WebFetch(domain:wirexsystems.com)",
+      "WebFetch(domain:www.zlti.com)",
+      "Bash(gh run:*)",
+      "Bash(gh api:*)",
+      "WebFetch(domain:api.github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(git -C /Users/tommy/pompelmi/pompelmi status)",
+      "Bash(git -C /Users/tommy/pompelmi/pompelmi log --oneline -5)",
+      "Bash(git pull:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m ':*)",
+      "Bash(git push:*)",
+      "Bash(grep -E '\\\\.\\(png|svg|ico|webp\\)$')"
+    ]
+  }
+}

package/LICENSE

@@ -1,21 +1,15 @@
-MIT License
+ISC License
 
-Copyright (c) 2025 Tommaso Bertocchi
+Copyright (c) 2024 pompelmi contributors
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,228 +1,204 @@
-<!-- ════════════════════════════════════════════════════════════════════
-     PIVOT NOTICE — read before using this package
-     ════════════════════════════════════════════════════════════════════ -->
-> [!CAUTION]
-> **v0.x is an experimental prototype. Do NOT use it in production.**
->
-> Pompelmi v0.x has **known Event Loop blocking issues** and makes overreaching
-> "scanner" claims that it cannot keep. This version is in **soft maintenance
-> only** — no new features, security patches only.
->
-> ---
->
-> **Pompelmi is pivoting for v1.0.**
->
-> The new identity is a **dead-simple, one-line utility wrapper** for Node.js
-> file uploads — not an "ultimate malware scanner". v1.0 will bundle standard,
-> well-understood checks (size limits, magic bytes, basic heuristics) into a
-> single convenient call that returns a traffic-light verdict:
->
-> ```js
-> const result = await pompelmi.scan(file);
-> // returns 'green', 'suspicious', or 'malicious'
-> ```
->
-> No magic promises. No impossible guarantees. Just saved developer time.
->
-> Follow the pivot → [GitHub Issues](https://github.com/pompelmi/pompelmi/issues) · [Discussions](https://github.com/pompelmi/pompelmi/discussions)
+<p align="center">
+  <img src="./src/grapefruit.png" width="96" alt="pompelmi logo">
+</p>
 
----
+<h1 align="center">pompelmi</h1>
 
-<div align="center">
-  <img src="./assets/logo.svg" alt="Pompelmi logo" width="120" />
-
-  <h1>Pompelmi</h1>
-
-  <p><strong>Secure file uploads in Node.js before storage.</strong></p>
-
-  <p>
-    Open-source route-level upload security for Node.js teams that need to
-    inspect untrusted files before disk, object storage, previews, or
-    downstream parsers.
-  </p>
-
-  <p><code>clean</code> · <code>suspicious</code> · <code>malicious</code></p>
-
-  <p>
-    MIME spoofing · risky archives · document and binary signals · optional
-    YARA
-  </p>
-
-  <p>
-    <sub>Express · Next.js · NestJS · Fastify · Koa · Nuxt/Nitro · S3 quarantine flows · CI/CD</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://www.npmjs.com/package/pompelmi"><img alt="npm total downloads" src="https://img.shields.io/npm/dt/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://github.com/pompelmi/pompelmi/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg" /></a>
-    <a href="https://nodejs.org"><img alt="Node.js 18+" src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" /></a>
-  </p>
-
-  > If Pompelmi fits how you think about upload security at the route
-  > level, starring the repo helps other Node.js teams find it.
-  > [★ Star on GitHub](https://github.com/pompelmi/pompelmi/stargazers)
-
-  <p>
-    <a href="https://pompelmi.app/"><strong>Docs</strong></a>
-    ·
-    <a href="https://pompelmi.app/getting-started/"><strong>Getting started</strong></a>
-    ·
-    <a href="https://pompelmi.app/#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>
-
-  <p><sub>Node.js 18+ · MIT</sub></p>
-</div>
+<p align="center"><strong>ClamAV for humans</strong></p>
 
 <p align="center">
-  <strong>Mentioned by</strong>
-  <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>,
-  <a href="https://github.com/dzharii/awesome-typescript">Awesome TypeScript</a>,
-  <a href="https://bytes.dev/archives/429">Bytes</a>,
-  and
-  <a href="https://www.detectionengineering.net/p/det-eng-weekly-124">Detection Engineering Weekly</a>
+  <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/license-ISC-blue.svg" alt="license">
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg" alt="platform">
+  <a href="https://www.npmjs.com/package/pompelmi?activeTab=dependencies"><img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies"></a>
 </p>
 
-> 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.
+---
+
+A minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that scans any file and returns a plain string: `"Clean"`, `"Malicious"`, or `"ScanError"`. No daemons. No cloud. No native bindings.
+
+## Table of contents
 
-## Quick Start
+- [Quickstart](#quickstart)
+- [How it works](#how-it-works)
+- [API](#api)
+  - [pompelmi.scan()](#pompelmiscanfilepath)
+- [Internal utilities](#internal-utilities)
+  - [ClamAVInstaller()](#clamavinstaller)
+  - [updateClamAVDatabase()](#updateclamavdatabase)
+- [Supported platforms](#supported-platforms)
+- [Installing ClamAV manually](#installing-clamav-manually)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [Security](#security)
+- [License](#license)
+
+---
 
-Install the core package:
+## Quickstart
 
 ```bash
 npm install pompelmi
 ```
 
-This is the core pattern: inspect bytes, get a verdict, and only store clean files.
+```js
+const pompelmi = require('pompelmi');
 
-```ts
-import { scanBytes, STRICT_PUBLIC_UPLOAD } from 'pompelmi';
-
-const report = await scanBytes(req.file.buffer, {
-  filename: req.file.originalname,
-  mimeType: req.file.mimetype,
-  policy: STRICT_PUBLIC_UPLOAD,
-  failClosed: true,
-});
-
-if (report.verdict !== 'clean') {
-  return res.status(422).json({
-    error: 'Upload blocked',
-    verdict: report.verdict,
-    reasons: report.reasons,
-  });
+const result = await pompelmi.scan('/path/to/file.zip');
+// "Clean" | "Malicious" | "ScanError"
+
+if (result === 'Malicious') {
+  throw new Error('File rejected: malware detected');
 }
+```
+
+## How it works
+
+1. **Validate** — pompelmi checks that the argument is a string and that the file exists before spawning anything.
+2. **Scan** — pompelmi spawns `clamscan --no-summary <filePath>` as a child process and reads the exit code.
+3. **Map** — the exit code is mapped to a result string. Unknown codes and spawn errors reject the Promise.
+
+No stdout parsing. No regex. No surprises.
+
+## API
 
-return res.status(200).json({ verdict: report.verdict });
+### `pompelmi.scan(filePath)`
+
+```ts
+pompelmi.scan(filePath: string): Promise<"Clean" | "Malicious" | "ScanError">
 ```
 
-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).
+| Parameter  | Type     | Description                             |
+|------------|----------|-----------------------------------------|
+| `filePath` | `string` | Absolute or relative path to the file. |
+
+**Resolves** to one of:
+
+| Result        | ClamAV exit code | Meaning                                                                                              |
+|---------------|:---:|------------------------------------------------------------------------------------------------------|
+| `"Clean"`     |  0  | No threats found.                                                                                    |
+| `"Malicious"` |  1  | A known virus or malware signature was matched.                                                      |
+| `"ScanError"` |  2  | The scan itself failed (I/O error, encrypted archive, permission denied). File status is unknown — treat as untrusted. |
+
+**Rejects** with an `Error` in these cases:
+
+| Condition | Error message |
+|-----------|---------------|
+| `filePath` is not a string | `filePath must be a string` |
+| File does not exist | `File not found: <path>` |
+| `clamscan` is not in PATH | `ENOENT` (from the OS) |
+| ClamAV returns an unknown exit code | `Unexpected exit code: N` |
+| `clamscan` process is killed by a signal | `Process killed by signal: <SIGNAL>` |
+
+**Example — full error handling:**
+
+```js
+const pompelmi = require('pompelmi');
+const path = require('path');
+
+async function safeScan(filePath) {
+  try {
+    const result = await pompelmi.scan(path.resolve(filePath));
+
+    if (result === 'ScanError') {
+      // The scan could not complete — treat the file as untrusted.
+      console.warn('Scan incomplete, rejecting file as precaution.');
+      return null;
+    }
+
+    return result; // "Clean" or "Malicious"
+  } catch (err) {
+    console.error('Scan failed:', err.message);
+    return null;
+  }
+}
+```
 
-## Why teams use Pompelmi
+## Internal utilities
 
-- File upload endpoints are not just form validation. Files can become risky after storage, extraction, rendering, or downstream parsing.
-- 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.
-- It gives Node.js teams a practical way to build secure file uploads with route-level decisions instead of bolting checks on after persistence.
+These modules are not part of the public npm API but are used internally to set up the ClamAV environment on a fresh machine.
 
-File upload vulnerabilities are the root cause of real CVEs across web frameworks. Application-layer inspection is the earliest point where the route still has full policy context — file class, trust level, storage path, and failure mode. Waiting until after storage removes most of that context and limits what the application can decide.
+### `ClamAVInstaller()`
 
-## What it checks
+Installs ClamAV using the platform's native package manager. Skips silently if ClamAV is already installed.
 
-- MIME sniffing, magic-byte validation, and extension mismatch detection
-- Risky archives such as ZIP bombs, traversal attempts, deep nesting, and entry-count abuse
-- Risky document and binary signals such as PDF actions, Office macro hints, PE headers, and polyglot files
-- Optional YARA-based matches when you want malware scanning uploads as part of the flow
-- Verdicts and reasons you can use for fail-closed routes, quarantine flows, and auditability
+```ts
+ClamAVInstaller(): Promise<string>
+```
 
-## Where it fits in the upload pipeline
+- Resolves with a status message string on success or skip.
+- Rejects if the install process exits with a non-zero code or if spawning the package manager fails.
 
-1. Receive the upload into memory or an isolated staging or quarantine area.
-2. Scan the bytes with a route policy.
-3. Act on the verdict: `clean`, `suspicious`, or `malicious`.
-4. Persist, quarantine, or reject based on the route's rules.
+| Platform | Package manager | Command |
+|----------|----------------|---------|
+| macOS    | Homebrew       | `brew install clamav` |
+| Linux    | apt-get        | `sudo apt-get install -y clamav clamav-daemon` |
+| Windows  | Chocolatey     | `choco install clamav -y` |
 
-That inspect-first, store-later shape is where Pompelmi is strongest.
+### `updateClamAVDatabase()`
 
-## What it is and isn't
+Downloads or updates the ClamAV virus definition database by running `freshclam`. Skips if `main.cvd` is already present on disk.
 
-| Approach | Useful for | What it misses |
-| --- | --- | --- |
-| Browser MIME and extension checks | Fast client-side hints and UX feedback | Client MIME and filenames are easy to spoof |
-| File-type or magic-byte validation only | Confirming a file looks like the claimed type | Archive abuse, risky internal structure, and route policy decisions |
-| Antivirus or YARA only | Known malicious matches and signature-style detection | Route context, spoofing checks, and before-storage handling |
-| 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 |
+```ts
+updateClamAVDatabase(): Promise<string>
+```
 
-<!-- search: file upload security Node.js, MIME spoofing protection, archive bomb defense -->
+- Resolves with a status message string on success or skip.
+- Rejects if `freshclam` exits with a non-zero code or if spawning fails.
 
-## Supported frameworks and workflows
+| Platform | Database path |
+|----------|--------------|
+| macOS    | `/usr/local/share/clamav/main.cvd` |
+| Linux    | `/var/lib/clamav/main.cvd` |
+| Windows  | `C:\ProgramData\ClamAV\main.cvd` |
 
-| Stack or workflow | Links |
-| --- | --- |
-| Express | [Docs](https://pompelmi.app/how-to/express/) · [Minimal example](./examples/express-minimal) · [Demo](./examples/demo) |
-| Next.js | [Docs](https://pompelmi.app/how-to/nextjs/) · [Example](./examples/next-app-router) · [Package](./packages/next-upload) |
-| NestJS | [Docs](https://pompelmi.app/how-to/nestjs/) · [Package](./packages/nestjs) · [Example app](./examples/nestjs-app) |
-| Fastify | [Docs](https://pompelmi.app/how-to/fastify/) · [Package](./packages/fastify-plugin) |
-| Koa | [Docs](https://pompelmi.app/how-to/koa/) · [Package](./packages/koa-middleware) |
-| Nuxt/Nitro | [Docs](https://pompelmi.app/how-to/nuxt-nitro/) · [Example](./examples/nuxt-nitro) |
-| 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/) |
-| CI/CD | [Use case](https://pompelmi.app/use-cases/cicd-artifact-scanning/) · [Blog](https://pompelmi.app/blog/cicd-scan-build-artifacts/) |
+## Supported platforms
 
-## Demo, preview, and examples
+| OS      | ClamAV install            | DB path checked                    |
+|---------|---------------------------|------------------------------------|
+| macOS   | `brew install clamav`     | `/usr/local/share/clamav/main.cvd` |
+| Linux   | `apt-get install clamav`  | `/var/lib/clamav/main.cvd`         |
+| Windows | `choco install clamav -y` | `C:\ProgramData\ClamAV\main.cvd`   |
 
-![Pompelmi upload security demo](assets/malware-detection-node-demo.gif)
+ClamAV must be installed on the host system. pompelmi does not bundle or download it.
 
-- [Browser preview](https://pompelmi.app/#browser-preview) for a fast local look at the verdict UX without uploading files anywhere
-- [Express demo](./examples/demo) for a tiny upload gate that returns `clean`, `suspicious`, or `malicious` before storage
-- [Examples index](./examples/README.md) for framework-specific and production-oriented patterns
-- [Docs home](https://pompelmi.app/) for guides, comparisons, use cases, and tutorials
+## Installing ClamAV manually
 
-Listed in Awesome JavaScript and Awesome TypeScript, and featured by Node Weekly, Stack Overflow, Help Net Security, Bytes, and Detection Engineering Weekly.
+```bash
+# macOS
+brew install clamav && freshclam
+
+# Linux (Debian / Ubuntu)
+sudo apt-get install -y clamav clamav-daemon && sudo freshclam
+
+# Windows (Chocolatey)
+choco install clamav -y
+```
 
-<!-- MENTIONS:START -->
+## Testing
+
+```bash
+npm test
+```
 
-## Mentioned by
+The test suite has two parts:
 
-- [Node Weekly](https://nodeweekly.com/issues/594)
-- [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
-- [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
-- [Awesome JavaScript](https://github.com/sorrycc/awesome-javascript)
-- [Awesome TypeScript](https://github.com/dzharii/awesome-typescript)
-- [Bytes #429](https://bytes.dev/archives/429) — bytes.dev (2025-10-03)
-- [Det. Eng. Weekly #124](https://www.detectionengineering.net/p/det-eng-weekly-124) — detectionengineering.net (2025-08-13)
-- [The Overflow #319](https://stackoverflow.blog/2026/03/04/the-overflow-319/) — stackoverflow.blog (2026-03-04)
-- [Hottest OSS tools Feb 2026](https://www.helpnetsecurity.com/2026/02/26/hottest-oss-tools-feb-2026/) — helpnetsecurity.com (2026-02-26)
-- [See all mentions](https://pompelmi.app/featured-in/)
+- **Unit tests** (`test/unit.test.js`) — run with Node's built-in test runner. Mock `cross-spawn` and platform dependencies; no ClamAV installation required.
+- **Integration tests** (`test/scan.test.js`) — spawn real `clamscan` processes against EICAR test files. Skipped automatically if `clamscan` is not found in PATH.
 
-<!-- MENTIONS:END -->
+## Contributing
 
-## Docs
+1. Fork the repository at [https://github.com/pompelmi/pompelmi](https://github.com/pompelmi/pompelmi).
+2. Create a feature branch: `git checkout -b feat/your-change`.
+3. Make your changes and run `npm test` to verify.
+4. Open a pull request against `main`.
 
-- [Getting started](https://pompelmi.app/getting-started/)
-- [Use cases](https://pompelmi.app/use-cases/)
-- [Comparisons](https://pompelmi.app/comparisons/)
-- [Tutorials](https://pompelmi.app/tutorials/)
-- [Browser preview](https://pompelmi.app/#browser-preview)
-- [Featured in](https://pompelmi.app/featured-in/)
-- [Translations](https://pompelmi.app/translations/)
+Please read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing.
 
-## Commercial support
+## Security
 
-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/).
+To report a vulnerability, see [SECURITY.md](./SECURITY.md).
 
-## Project
+## License
 
-- [Contributing](./CONTRIBUTING.md)
-- [Security](./SECURITY.md)
-- [Roadmap](./ROADMAP.md)
-- [GitHub Discussions](https://github.com/pompelmi/pompelmi/discussions)
-- [License](./LICENSE)
+[ISC](./LICENSE) — © pompelmi contributors

package/eslint.config.mjs

@@ -0,0 +1,8 @@
+import js from "@eslint/js";
+import globals from "globals";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  { files: ["**/*.{js,mjs,cjs}"], plugins: { js }, extends: ["js/recommended"], languageOptions: { globals: globals.node } },
+  { files: ["**/*.js"], languageOptions: { sourceType: "commonjs" } },
+]);