pompelmi 1.0.0 → 1.1.0

package/.claude/settings.local.json

@@ -34,7 +34,12 @@
       "Bash(git add:*)",
       "Bash(git commit -m ':*)",
       "Bash(git push:*)",
-      "Bash(grep -E '\\\\.\\(png|svg|ico|webp\\)$')"
+      "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)"
     ]
   }
 }

package/README.md

@@ -22,7 +22,8 @@ A minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that scans an
 - [Quickstart](#quickstart)
 - [How it works](#how-it-works)
 - [API](#api)
-  - [pompelmi.scan()](#pompelmiscanfilepath)
+  - [pompelmi.scan()](#pompelmiscanfilepath-options)
+- [Docker / remote scanning](#docker--remote-scanning)
 - [Internal utilities](#internal-utilities)
   - [ClamAVInstaller()](#clamavinstaller)
   - [updateClamAVDatabase()](#updateclamavdatabase)
@@ -62,15 +63,16 @@ No stdout parsing. No regex. No surprises.
 
 ## API
 
-### `pompelmi.scan(filePath)`
+### `pompelmi.scan(filePath, [options])`
 
 ```ts
-pompelmi.scan(filePath: string): Promise<"Clean" | "Malicious" | "ScanError">
+pompelmi.scan(filePath: string, options?: { host?: string; port?: number; timeout?: number }): Promise<"Clean" | "Malicious" | "ScanError">
 ```
 
 | Parameter  | Type     | Description                             |
 |------------|----------|-----------------------------------------|
 | `filePath` | `string` | Absolute or relative path to the file. |
+| `options`  | `object` | Optional. Omit to use the local `clamscan` CLI. Pass `host` / `port` to scan via a clamd TCP socket instead. See [docs/api.md](./docs/api.md) for the full reference. |
 
 **Resolves** to one of:
 
@@ -114,6 +116,21 @@ async function safeScan(filePath) {
 }
 ```
 
+## Docker / remote scanning
+
+If ClamAV runs in a Docker container (or anywhere on the network), pass `host` and `port` — everything else stays the same.
+
+```js
+const result = await pompelmi.scan('/path/to/upload.zip', {
+  host: '127.0.0.1',
+  port: 3310,
+});
+```
+
+See [docs/docker.md](./docs/docker.md) for the `docker-compose.yml` snippet and first-boot notes.
+
+---
+
 ## Internal utilities
 
 These modules are not part of the public npm API but are used internally to set up the ClamAV environment on a fresh machine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.0.0",
+  "version": "1.1.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,6 +1,7 @@
 const spawn = require("cross-spawn");
 const fs = require("fs");
 const { SCAN_RESULTS } = require('./config.js');
+const { scanViaClamd } = require('./ClamdScanner.js');
 
 const MESSAGES = {
     FILE_NOT_FOUND:        (filePath) => `File not found: ${filePath}`,
@@ -8,7 +9,12 @@ const MESSAGES = {
     PROCESS_KILLED:        (signal)   => `Process killed by signal: ${signal}`,
 };
 
-function scan(filePath) {
+function scan(filePath, options = {}) {
+    // When a host or port is provided, delegate to the clamd TCP path.
+    if (options.host !== undefined || options.port !== undefined) {
+        return scanViaClamd(filePath, options);
+    }
+
     return new Promise((resolve, reject) => {
         if (typeof filePath !== 'string') {
             return reject(new Error('filePath must be a string'));

package/src/ClamdScanner.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const net = require('net');
+const fs  = require('fs');
+
+// ClamAV INSTREAM protocol:
+//   1. Send "zINSTREAM\0"
+//   2. Send N chunks, each prefixed with a 4-byte big-endian length
+//   3. Terminate with four zero bytes
+//   4. Read response line: "stream: OK", "stream: <name> FOUND", or an error
+const CLAMD_INSTREAM = Buffer.from('zINSTREAM\0');
+const CHUNK_SIZE     = 64 * 1024;  // 64 KB — well within clamd's default StreamMaxLength
+
+function parseClamdResponse(raw) {
+    const text = raw.toString('utf8').trim();
+    if (text === 'stream: OK')      return 'Clean';
+    if (text.endsWith(' FOUND'))    return 'Malicious';
+    return 'ScanError';
+}
+
+/**
+ * Scan a file by streaming it to a running clamd instance over TCP.
+ *
+ * @param {string} filePath   - Absolute or relative path to the file to scan.
+ * @param {object} [options]
+ * @param {string} [options.host='127.0.0.1']
+ * @param {number} [options.port=3310]
+ * @param {number} [options.timeout=15000]  - Socket idle timeout in ms.
+ * @returns {Promise<'Clean'|'Malicious'|'ScanError'>}
+ */
+function scanViaClamd(filePath, { host = '127.0.0.1', port = 3310, timeout = 15_000 } = {}) {
+    return new Promise((resolve, reject) => {
+        if (typeof filePath !== 'string') {
+            return reject(new Error('filePath must be a string'));
+        }
+        if (!fs.existsSync(filePath)) {
+            return reject(new Error(`File not found: ${filePath}`));
+        }
+
+        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);
+
+            const fileStream = fs.createReadStream(filePath, { highWaterMark: CHUNK_SIZE });
+
+            fileStream.on('error', (err) => settle(reject, err));
+
+            fileStream.on('data', (chunk) => {
+                const header = Buffer.allocUnsafe(4);
+                header.writeUInt32BE(chunk.length, 0);
+                socket.write(header);
+                socket.write(chunk);
+            });
+
+            fileStream.on('end', () => {
+                socket.write(Buffer.alloc(4)); // terminating zero-length chunk
+                socket.end();
+            });
+        });
+    });
+}
+
+module.exports = { scanViaClamd };

package/test_out.txt

@@ -0,0 +1,74 @@
+ClamAV is already installed, skipping.
+Current platform is not supported.
+Installation completed successfully!
+Virus database already present, skipping.
+Current platform is not supported.
+Downloading virus definitions...
+Database updated successfully!
+Downloading virus definitions...
+Downloading virus definitions...
+▶ InstallerCommand
+  ▶ getInstallerCommand
+    ✔ darwin  → brew install clamav (1.172833ms)
+    ✔ linux   → sudo apt-get install (0.163833ms)
+    ✔ win32   → choco install clamav (0.07125ms)
+    ✔ unknown → [null, []] (0.054792ms)
+  ✔ getInstallerCommand (1.877625ms)
+  ▶ getUpdaterCommand
+    ✔ darwin  → freshclam (0.094625ms)
+    ✔ linux   → sudo freshclam (0.255ms)
+    ✔ win32   → freshclam (0.055834ms)
+    ✔ unknown → [null, []] (0.308416ms)
+  ✔ getUpdaterCommand (0.965833ms)
+✔ InstallerCommand (3.261333ms)
+▶ ClamAVScanner
+  ✔ rejects if filePath is not a string (10.062042ms)
+  ✔ rejects if file does not exist (0.441042ms)
+  ✔ exit code 0  → resolves to "Clean" (0.847959ms)
+  ✔ exit code 1  → resolves to "Malicious" (0.890875ms)
+  ✔ exit code 2  → resolves to "ScanError" (0.5805ms)
+  ✔ exit code 99 → rejects with exit code message (0.535625ms)
+  ✔ spawn error  → rejects with the error (0.550542ms)
+  ✔ signal kill  → rejects with signal name (0.405667ms)
+✔ ClamAVScanner (14.502167ms)
+▶ ClamAVInstaller
+  ✔ resolves if ClamAV is already installed (1.17225ms)
+  ✔ resolves with platform-not-supported message (1.279459ms)
+  ✔ resolves after successful installation (0.755125ms)
+  ✔ rejects when installation exits non-zero (0.553375ms)
+  ✔ rejects on spawn error (0.969208ms)
+✔ ClamAVInstaller (4.845042ms)
+▶ ClamdScanner
+  ✔ rejects if filePath is not a string (0.186125ms)
+  ✔ rejects if file does not exist (0.371125ms)
+  ✔ "stream: OK"              → "Clean" (0.388458ms)
+  ✔ "stream: ... FOUND"       → "Malicious" (0.163792ms)
+  ✔ any other clamd response  → "ScanError" (0.294458ms)
+  ✔ socket error (ECONNREFUSED) → rejects with that error (0.187ms)
+  ✔ socket timeout              → rejects with timeout message (0.119208ms)
+  ✔ file read stream error      → rejects with that error (0.118084ms)
+  ✔ sends zINSTREAM command, chunk header, chunk data, and terminator (0.327083ms)
+✔ ClamdScanner (2.320125ms)
+▶ ClamAVScanner (TCP routing)
+  ✔ routes to clamd when { port } is given (2.303ms)
+  ✔ routes to clamd when { host } is given (0.207792ms)
+  ✔ routes to clamd when { host, port } are both given (0.27525ms)
+  ✔ forwards filePath and options unchanged to scanViaClamd (0.267083ms)
+  ✔ uses the CLI path when called without options (0.31125ms)
+  ✔ uses the CLI path when called with an empty options object {} (0.318041ms)
+✔ ClamAVScanner (TCP routing) (3.793958ms)
+▶ ClamAVDatabaseUpdater
+  ✔ resolves if database is already present (0.793833ms)
+  ✔ resolves with platform-not-supported message (0.326166ms)
+  ✔ resolves after successful update (0.37675ms)
+  ✔ rejects when update exits non-zero (0.330167ms)
+  ✔ rejects on spawn error (0.545833ms)
+✔ ClamAVDatabaseUpdater (2.478542ms)
+ℹ tests 41
+ℹ suites 8
+ℹ pass 41
+ℹ fail 0
+ℹ cancelled 0
+ℹ skipped 0
+ℹ todo 0
+ℹ duration_ms 107.87375