pompelmi 1.2.4 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
   <img src="./src/grapefruit.png" width="88" alt="pompelmi logo">
 </p>
 
-# pompelmi — ClamAV Antivirus Scanning for Node.js
+<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,10 +13,10 @@
   <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">
+  <img src="https://github.com/pompelmi/pompelmi/actions/workflows/release.yml/badge.svg" alt="npm publish">
 </p>
 
-![Node.js CI](https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg)
-
 ---
 
 ## Overview
@@ -43,6 +43,8 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 ## 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
+- `scanStream(stream, [options])` — scan a Readable stream directly. In TCP mode, streamed to clamd with no disk I/O.
 - 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
@@ -214,6 +216,32 @@ 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.');
+```
+
+### Scan a Stream
+
+```js
+const { scanStream, Verdict } = require('pompelmi');
+const { Readable } = require('stream');
+
+// Useful for S3 getObject, HTTP downloads, or any piped source
+const stream = s3.getObject({ Bucket, Key }).createReadStream();
+const result = await scanStream(stream);
+
+if (result === Verdict.Malicious) throw new Error('Malware detected.');
+if (result === Verdict.ScanError) console.warn('Scan incomplete.');
+```
+
 ---
 
 ## Docker / Remote Scanning
@@ -286,6 +314,60 @@ 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.
+
+---
+
+### `scanStream(stream, [options])`
+
+```ts
+scanStream(
+  stream: Readable,
+  options?: { host?: string; port?: number; timeout?: number }
+): Promise<symbol>
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `stream` | `Readable` | Node.js Readable stream 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 |
+|---|---|
+| `stream` is not a Readable | `stream must be a Readable` |
+| Stream emits error | propagated as-is |
+
+In TCP mode (`host` or `port` provided), the stream is piped directly to clamd via the INSTREAM protocol — no data is written to disk. In local mode, the stream is piped to a temp file in `os.tmpdir()` that is deleted automatically in a `finally` block.
+
+---
+
 ### `ClamAVInstaller()` _(internal)_
 
 Installs ClamAV using the platform's native package manager. Resolves immediately if ClamAV is already installed.
@@ -349,6 +431,7 @@ The [`examples/`](./examples/) directory contains standalone runnable scripts. E
 | [`scan-multiple-files.js`](examples/scan-multiple-files.js) | Concurrent scans with `Promise.all` |
 | [`scan-directory.js`](examples/scan-directory.js) | Recursively scan every file in a directory |
 | [`scan-buffer.js`](examples/scan-buffer.js) | Scan an in-memory Buffer via a temp-file shim |
+| [`scan-stream.js`](examples/scan-stream.js) | Scan an S3 getObject Readable stream with scanStream() |
 | [`rest-api-server.js`](examples/rest-api-server.js) | Minimal HTTP server exposing `POST /scan` |
 | [`s3-scan-before-upload.js`](examples/s3-scan-before-upload.js) | Scan locally, then upload to S3 only if clean |
 | [`cli-scan.js`](examples/cli-scan.js) | CLI tool: scan file paths, exit non-zero on threats |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.2.4",
+  "version": "1.4.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",

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,12 @@
-const { nativeSpawn: spawn } = require('./spawn.js');
-const fs = require("fs");
-const { SCAN_RESULTS } = require('./config.js');
-const { scanViaClamd } = require('./ClamdScanner.js');
+const { nativeSpawn: spawn }   = require('./spawn.js');
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const { Readable }               = require('stream');
+const { SCAN_RESULTS }           = require('./config.js');
+const { scanViaClamd }           = require('./ClamdScanner.js');
+const { scanBufferViaClamd }     = require('./BufferScanner.js');
+const { scanStreamViaClamd }     = require('./StreamScanner.js');
 
 const MESSAGES = {
     FILE_NOT_FOUND:        (filePath) => `File not found: ${filePath}`,
@@ -34,4 +39,65 @@ 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, () => {});
+    }
+}
+
+async function scanStream(stream, options = {}) {
+    if (!(stream instanceof Readable)) {
+        throw new Error('stream must be a Readable');
+    }
+
+    if (options.host !== undefined || options.port !== undefined) {
+        return scanStreamViaClamd(stream, options);
+    }
+
+    const tmpPath = path.join(
+        os.tmpdir(),
+        `pompelmi-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        function settle(err) {
+            if (settled) return;
+            settled = true;
+            if (err) reject(err);
+            else resolve();
+        }
+        const writable = fs.createWriteStream(tmpPath);
+        stream.on('error', settle);
+        writable.on('error', settle);
+        writable.on('finish', () => settle(null));
+        stream.pipe(writable);
+    });
+
+    try {
+        return await scan(tmpPath);
+    } finally {
+        fs.unlink(tmpPath, () => {});
+    }
+}
+
+module.exports = { scan, scanBuffer, scanStream };

package/src/StreamScanner.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const net         = require('net');
+const { Verdict } = require('./verdicts.js');
+
+const CLAMD_INSTREAM = Buffer.from('zINSTREAM\0');
+
+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 a Readable stream by piping it to a running clamd instance over TCP.
+ * No data is written to disk.
+ *
+ * @param {import('stream').Readable} stream
+ * @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 scanStreamViaClamd(stream, { 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);
+
+            stream.on('error', (err) => settle(reject, err));
+
+            stream.on('data', (chunk) => {
+                const header = Buffer.allocUnsafe(4);
+                header.writeUInt32BE(chunk.length, 0);
+                socket.write(header);
+                socket.write(chunk);
+            });
+
+            stream.on('end', () => {
+                socket.write(Buffer.alloc(4)); // terminating zero-length chunk
+                socket.end();
+            });
+        });
+    });
+}
+
+module.exports = { scanStreamViaClamd };

package/src/index.js

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

package/.claude/settings.local.json

@@ -1,51 +0,0 @@
-{
-  "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\\)$')",
-      "Bash(ls -d /Users/tommy/pompelmi/pompelmi/*/)",
-      "Bash(node --test test/unit.test.js)",
-      "Bash(echo \"exit:$?\")",
-      "Read(//tmp/**)",
-      "Bash(tee /Users/tommy/pompelmi/pompelmi/test_out.txt)",
-      "Bash(npm install:*)",
-      "Bash(npm ls:*)",
-      "Bash(wait)",
-      "Bash(git rebase *)",
-      "Bash(python3 *)",
-      "Bash(git *)"
-    ]
-  }
-}