pompelmi 1.3.0 → 1.5.0

package/README.md

@@ -7,13 +7,31 @@
 <p align="center"><strong>ClamAV antivirus scanning for Node.js — clean, typed, zero dependencies.</strong></p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/dw/pompelmi" alt="npm weekly downloads"></a>
-  <a href="https://github.com/pompelmi/pompelmi"><img src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social" alt="GitHub stars"></a>
-  <img src="https://img.shields.io/badge/docker-available-blue?logo=docker" alt="Docker available">
+  <img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version">
+  <img src="https://img.shields.io/npm/dw/pompelmi" alt="npm downloads">
   <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://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies">
+</p>
+
+<p align="center">
   <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>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/express-available-black?logo=express" alt="Express">
+  <img src="https://img.shields.io/badge/fastify-available-black?logo=fastify" alt="Fastify">
+  <img src="https://img.shields.io/badge/nestjs-available-red?logo=nestjs" alt="NestJS">
+  <img src="https://img.shields.io/badge/koa-available-lightgrey?logo=node.js" alt="Koa">
+  <img src="https://img.shields.io/badge/hono-available-orange" alt="Hono">
+  <img src="https://img.shields.io/badge/next.js-available-black?logo=next.js" alt="Next.js">
+  <img src="https://img.shields.io/badge/sveltekit-available-red?logo=svelte" alt="SvelteKit">
+  <img src="https://img.shields.io/badge/remix-available-black?logo=remix" alt="Remix">
+  <img src="https://img.shields.io/badge/docker-available-blue?logo=docker" alt="Docker">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/pompelmi/pompelmi?style=social" alt="GitHub stars">
 </p>
 
 ---
@@ -43,6 +61,8 @@ 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.
+- `scanDirectory(dirPath, [options])` — recursively scan every file in a directory, returns clean/malicious/errors arrays
 - 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 +234,22 @@ const files    = ['/uploads/a.pdf', '/uploads/b.zip', '/uploads/c.png'];
 const results = await Promise.all(files.map((f) => scan(f)));
 ```
 
+### Scan a Directory
+
+```js
+const fs = require('fs');
+const { scanDirectory } = require('pompelmi');
+
+const results = await scanDirectory('/uploads');
+
+console.log('Clean:', results.clean);
+console.log('Malicious:', results.malicious);
+console.log('Errors:', results.errors);
+
+// Delete all malicious files
+results.malicious.forEach(f => fs.unlinkSync(f));
+```
+
 ### Scan a Buffer
 
 ```js
@@ -226,6 +262,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 +375,61 @@ 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.
+
+---
+
+### `scanDirectory(dirPath, [options])`
+
+```ts
+scanDirectory(
+  dirPath: string,
+  options?: { host?: string; port?: number; timeout?: number }
+): Promise<{ clean: string[], malicious: string[], errors: string[] }>
+```
+
+Recursively scans every file in `dirPath` and returns three arrays of absolute paths.
+
+| Field | Type | Description |
+|---|---|---|
+| `clean` | `string[]` | Paths of files with no threats found |
+| `malicious` | `string[]` | Paths of files with a matched signature |
+| `errors` | `string[]` | Paths of files that could not be scanned |
+
+Per-file scan failures are caught and collected into `errors` — the function never throws because of an individual file.
+
+**Rejects** with an `Error` in these cases:
+
+| Condition | Error message |
+|---|---|
+| `dirPath` is not a string | `dirPath must be a string` |
+| Directory does not exist | `Directory not found: <path>` |
+
+---
+
 ### `ClamAVInstaller()` _(internal)_
 
 Installs ClamAV using the platform's native package manager. Resolves immediately if ClamAV is already installed.
@@ -388,6 +493,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.5.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",
@@ -36,6 +36,9 @@
     "test": "node --test test/unit.test.js && node test/scan.test.js",
     "lint": "eslint src/"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {},
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/ClamAVScanner.js

@@ -1,10 +1,13 @@
-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 { Verdict }                = require('./verdicts.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 +65,76 @@ 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, () => {});
+    }
+}
+
+async function scanDirectory(dirPath, options = {}) {
+    if (typeof dirPath !== 'string') {
+        throw new Error('dirPath must be a string');
+    }
+    if (!fs.existsSync(dirPath)) {
+        throw new Error(`Directory not found: ${dirPath}`);
+    }
+
+    const entries = fs.readdirSync(dirPath, { recursive: true });
+    const files = entries
+        .map(entry => path.join(dirPath, entry))
+        .filter(fullPath => fs.statSync(fullPath).isFile());
+
+    const results = await Promise.all(
+        files.map(async (filePath) => {
+            try {
+                return { filePath, verdict: await scan(filePath, options) };
+            } catch {
+                return { filePath, verdict: null };
+            }
+        })
+    );
+
+    const clean = [];
+    const malicious = [];
+    const errors = [];
+
+    for (const { filePath, verdict } of results) {
+        if (verdict === Verdict.Clean)     clean.push(filePath);
+        else if (verdict === Verdict.Malicious) malicious.push(filePath);
+        else                               errors.push(filePath);
+    }
+
+    return { clean, malicious, errors };
+}
+
+module.exports = { scan, scanBuffer, scanStream, scanDirectory };

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, scanDirectory } = require('./ClamAVScanner.js');
+const { Verdict }                                     = require('./verdicts.js');
 
-module.exports = { scan, scanBuffer, Verdict };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, 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 *)"
-    ]
-  }
-}