pompelmi 1.2.3 → 1.3.0

package/.claude/settings.local.json

@@ -44,7 +44,9 @@
       "Bash(npm ls:*)",
       "Bash(wait)",
       "Bash(git rebase *)",
-      "Bash(python3 *)"
+      "Bash(python3 *)",
+      "Bash(git *)",
+      "Bash(npm test *)"
     ]
   }
 }

package/README.md

@@ -2,7 +2,7 @@
   <img src="./src/grapefruit.png" width="88" alt="pompelmi logo">
 </p>
 
-<h1 align="center">pompelmi</h1>
+<h1 align="center">pompelmi — ClamAV Antivirus Scanning for Node.js</h1>
 
 <p align="center"><strong>ClamAV antivirus scanning for Node.js — clean, typed, zero dependencies.</strong></p>
 
@@ -13,13 +13,14 @@
   <img src="https://img.shields.io/badge/docker-available-blue?logo=docker" alt="Docker available">
   <img src="https://img.shields.io/badge/license-ISC-blue.svg" alt="license">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
+  <img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="Node.js CI">
 </p>
 
 ---
 
 ## Overview
 
-pompelmi is a minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that exposes a single async function — `scan()` — and returns one of three typed verdict Symbols: `Verdict.Clean`, `Verdict.Malicious`, or `Verdict.ScanError`.
+pompelmi is a minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that exposes a single async function — `scan()` — and returns one of three typed verdict Symbols: `Verdict.Clean`, `Verdict.Malicious`, or `Verdict.ScanError`. Full documentation at [pompelmi.app](https://pompelmi.app).
 
 It supports two scanning modes:
 
@@ -30,9 +31,18 @@ No cloud. No daemon required for local mode. No native bindings. Zero runtime de
 
 ---
 
+## Why pompelmi
+
+If you need to **scan file uploads for viruses in Node.js**, integrate **ClamAV with Express or Fastify**, or add **antivirus scanning to any upload pipeline**, pompelmi is the simplest path.
+
+Most integrations require parsing ClamAV's stdout with regex, managing a clamd daemon, or working around unmaintained packages. pompelmi does none of that: one function call, exit-code-mapped verdicts, zero dependencies.
+
+---
+
 ## Features
 
 - Single `scan(filePath, [options])` function — works locally or against a remote clamd instance
+- `scanBuffer(buffer, [options])` — scan in-memory Buffers directly, no temp file required in TCP mode
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
 - Full TCP/clamd support via the INSTREAM protocol with configurable host, port, and timeout
 - Built-in helpers to install ClamAV and update virus definitions programmatically
@@ -54,6 +64,8 @@ pompelmi does not bundle or automatically download ClamAV. Install it once per m
 
 ## Installation
 
+See [pompelmi.app](https://pompelmi.app) for the full getting-started guide.
+
 ```bash
 # npm
 npm install pompelmi
@@ -202,6 +214,18 @@ const files    = ['/uploads/a.pdf', '/uploads/b.zip', '/uploads/c.png'];
 const results = await Promise.all(files.map((f) => scan(f)));
 ```
 
+### Scan a Buffer
+
+```js
+const { scanBuffer, Verdict } = require('pompelmi');
+
+// Useful with multer memoryStorage or any in-memory upload
+const result = await scanBuffer(req.file.buffer);
+
+if (result === Verdict.Malicious) throw new Error('Malware detected.');
+if (result === Verdict.ScanError) console.warn('Scan incomplete.');
+```
+
 ---
 
 ## Docker / Remote Scanning
@@ -274,6 +298,33 @@ Verdict.ScanError.description // 'ScanError'
 
 ---
 
+### `scanBuffer(buffer, [options])`
+
+```ts
+scanBuffer(
+  buffer: Buffer,
+  options?: { host?: string; port?: number; timeout?: number }
+): Promise<symbol>
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `buffer` | `Buffer` | The in-memory buffer to scan |
+| `options` | `object` | Same options as `scan()` — host, port, timeout |
+
+**Returns** the same three Symbol verdicts as `scan()`: `Verdict.Clean`, `Verdict.Malicious`, `Verdict.ScanError`.
+
+**Rejects** with the same error types as `scan()` where applicable, plus:
+
+| Condition | Error message |
+|---|---|
+| `buffer` is not a Buffer | `buffer must be a Buffer` |
+| `buffer` is empty | `buffer is empty` |
+
+In TCP mode (`host` or `port` provided), the buffer is streamed directly to clamd via the INSTREAM protocol — no data is written to disk. In local mode, a temp file is written to `os.tmpdir()` and deleted automatically in a `finally` block regardless of outcome.
+
+---
+
 ### `ClamAVInstaller()` _(internal)_
 
 Installs ClamAV using the platform's native package manager. Resolves immediately if ClamAV is already installed.
@@ -384,3 +435,7 @@ Please read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing. To r
 ## License
 
 [ISC](./LICENSE) — © pompelmi contributors
+
+---
+
+[pompelmi.app](https://pompelmi.app) · [npm](https://www.npmjs.com/package/pompelmi) · [GitHub](https://github.com/pompelmi/pompelmi)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "ClamAV for humans — scan any file and get back Clean, Malicious, or ScanError. No daemons. No cloud. No native bindings.",
   "license": "ISC",
   "author": "pompelmi contributors",
@@ -15,18 +15,19 @@
   "keywords": [
     "clamav",
     "antivirus",
-    "malware",
     "virus-scan",
-    "file-scan",
+    "malware",
+    "file-upload",
     "security",
+    "scan",
     "clamscan",
-    "malware-detection",
-    "virus-detection",
-    "file-upload-security",
-    "upload-scan",
-    "nodejs-security",
     "clamd",
-    "eicar",
+    "instream",
+    "nodejs",
+    "express",
+    "fastify",
+    "nestjs",
+    "multer",
     "zero-dependencies"
   ],
   "type": "commonjs",

package/src/BufferScanner.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const net         = require('net');
+const { Verdict } = require('./verdicts.js');
+
+const CLAMD_INSTREAM = Buffer.from('zINSTREAM\0');
+const CHUNK_SIZE     = 64 * 1024;
+
+function parseClamdResponse(raw) {
+    const text = raw.toString('utf8').trim();
+    if (text === 'stream: OK')   return Verdict.Clean;
+    if (text.endsWith(' FOUND')) return Verdict.Malicious;
+    return Verdict.ScanError;
+}
+
+/**
+ * Scan an in-memory Buffer by streaming it to a running clamd instance over TCP.
+ * No data is written to disk.
+ *
+ * @param {Buffer} buffer
+ * @param {object} [options]
+ * @param {string} [options.host='127.0.0.1']
+ * @param {number} [options.port=3310]
+ * @param {number} [options.timeout=15000]
+ * @returns {Promise<symbol>}
+ */
+function scanBufferViaClamd(buffer, { host = '127.0.0.1', port = 3310, timeout = 15_000 } = {}) {
+    return new Promise((resolve, reject) => {
+        const socket  = net.createConnection({ host, port });
+        const chunks  = [];
+        let   settled = false;
+
+        function settle(fn, value) {
+            if (settled) return;
+            settled = true;
+            socket.destroy();
+            fn(value);
+        }
+
+        socket.setTimeout(timeout);
+        socket.on('timeout', () =>
+            settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
+        );
+        socket.on('error', (err) => settle(reject, err));
+        socket.on('data',  (chunk) => chunks.push(chunk));
+        socket.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
+
+        socket.on('connect', () => {
+            socket.write(CLAMD_INSTREAM);
+
+            let offset = 0;
+            while (offset < buffer.length) {
+                const chunk  = buffer.slice(offset, offset + CHUNK_SIZE);
+                const header = Buffer.allocUnsafe(4);
+                header.writeUInt32BE(chunk.length, 0);
+                socket.write(header);
+                socket.write(chunk);
+                offset += chunk.length;
+            }
+
+            socket.write(Buffer.alloc(4)); // terminating zero-length chunk
+            socket.end();
+        });
+    });
+}
+
+module.exports = { scanBufferViaClamd };

package/src/ClamAVScanner.js

@@ -1,7 +1,10 @@
 const { nativeSpawn: spawn } = require('./spawn.js');
-const fs = require("fs");
-const { SCAN_RESULTS } = require('./config.js');
-const { scanViaClamd } = require('./ClamdScanner.js');
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const { SCAN_RESULTS }       = require('./config.js');
+const { scanViaClamd }       = require('./ClamdScanner.js');
+const { scanBufferViaClamd } = require('./BufferScanner.js');
 
 const MESSAGES = {
     FILE_NOT_FOUND:        (filePath) => `File not found: ${filePath}`,
@@ -34,4 +37,29 @@ function scan(filePath, options = {}) {
     });
 }
 
-module.exports = { scan };
+async function scanBuffer(buffer, options = {}) {
+    if (!Buffer.isBuffer(buffer)) {
+        throw new Error('buffer must be a Buffer');
+    }
+    if (buffer.length === 0) {
+        throw new Error('buffer is empty');
+    }
+
+    if (options.host !== undefined || options.port !== undefined) {
+        return scanBufferViaClamd(buffer, options);
+    }
+
+    const tmpPath = path.join(
+        os.tmpdir(),
+        `pompelmi-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+
+    fs.writeFileSync(tmpPath, buffer);
+    try {
+        return await scan(tmpPath);
+    } finally {
+        fs.unlink(tmpPath, () => {});
+    }
+}
+
+module.exports = { scan, scanBuffer };

package/src/index.js

@@ -1,4 +1,4 @@
-const { scan }    = require('./ClamAVScanner.js');
-const { Verdict } = require('./verdicts.js');
+const { scan, scanBuffer } = require('./ClamAVScanner.js');
+const { Verdict }          = require('./verdicts.js');
 
-module.exports = { scan, Verdict };
+module.exports = { scan, scanBuffer, Verdict };