pompelmi 1.3.0 → 1.4.0

package/README.md

@@ -14,6 +14,7 @@
   <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>
 
 ---
@@ -43,6 +44,7 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 
 - 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
@@ -226,6 +228,20 @@ 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
@@ -325,6 +341,33 @@ In TCP mode (`host` or `port` provided), the buffer is streamed directly to clam
 
 ---
 
+### `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.
@@ -388,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.3.0",
+  "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/ClamAVScanner.js

@@ -1,10 +1,12 @@
-const { nativeSpawn: spawn } = require('./spawn.js');
+const { nativeSpawn: spawn }   = require('./spawn.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 { 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}`,
@@ -62,4 +64,40 @@ async function scanBuffer(buffer, options = {}) {
     }
 }
 
-module.exports = { scan, scanBuffer };
+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, scanBuffer } = require('./ClamAVScanner.js');
-const { Verdict }          = require('./verdicts.js');
+const { scan, scanBuffer, scanStream } = require('./ClamAVScanner.js');
+const { Verdict }                       = require('./verdicts.js');
 
-module.exports = { scan, scanBuffer, Verdict };
+module.exports = { scan, scanBuffer, scanStream, Verdict };

package/.claude/settings.local.json

@@ -1,52 +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 *)",
-      "Bash(npm test *)"
-    ]
-  }
-}