pompelmi 1.0.0 → 1.2.0

package/.claude/settings.local.json

@@ -34,7 +34,14 @@
       "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)",
+      "Bash(npm install:*)",
+      "Bash(npm ls:*)"
     ]
   }
 }

package/README.md

@@ -15,14 +15,15 @@
 
 ---
 
-A minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that scans any file and returns a plain string: `"Clean"`, `"Malicious"`, or `"ScanError"`. No daemons. No cloud. No native bindings.
+A minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that scans any file and returns a typed `Verdict` Symbol: `Verdict.Clean`, `Verdict.Malicious`, or `Verdict.ScanError`. No daemons. No cloud. No native bindings. Zero runtime dependencies.
 
 ## Table of contents
 
 - [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)
@@ -42,12 +43,11 @@ npm install pompelmi
 ```
 
 ```js
-const pompelmi = require('pompelmi');
+const { scan, Verdict } = require('pompelmi');
 
-const result = await pompelmi.scan('/path/to/file.zip');
-// "Clean" | "Malicious" | "ScanError"
+const result = await scan('/path/to/file.zip');
 
-if (result === 'Malicious') {
+if (result === Verdict.Malicious) {
   throw new Error('File rejected: malware detected');
 }
 ```
@@ -62,23 +62,29 @@ No stdout parsing. No regex. No surprises.
 
 ## API
 
-### `pompelmi.scan(filePath)`
+### `pompelmi.scan(filePath, [options])`
 
 ```ts
-pompelmi.scan(filePath: string): Promise<"Clean" | "Malicious" | "ScanError">
+scan(filePath: string, options?: { host?: string; port?: number; timeout?: number }): Promise<symbol>
+// resolves to one of: Verdict.Clean | Verdict.Malicious | Verdict.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.html](./docs/api.html) for the full reference. |
 
 **Resolves** to one of:
 
-| Result        | ClamAV exit code | Meaning                                                                                              |
-|---------------|:---:|------------------------------------------------------------------------------------------------------|
-| `"Clean"`     |  0  | No threats found.                                                                                    |
-| `"Malicious"` |  1  | A known virus or malware signature was matched.                                                      |
-| `"ScanError"` |  2  | The scan itself failed (I/O error, encrypted archive, permission denied). File status is unknown — treat as untrusted. |
+| Result             | ClamAV exit code | Meaning                                                                                              |
+|--------------------|:---:|------------------------------------------------------------------------------------------------------|
+| `Verdict.Clean`     |  0  | No threats found.                                                                                    |
+| `Verdict.Malicious` |  1  | A known virus or malware signature was matched.                                                      |
+| `Verdict.ScanError` |  2  | The scan itself failed (I/O error, encrypted archive, permission denied). File status is unknown — treat as untrusted. |
+
+> **Reading the verdict as a string** — each Verdict Symbol carries a `.description` property
+> (`Verdict.Clean.description === 'Clean'`) for logging or serialisation without comparing against
+> raw strings in application logic.
 
 **Rejects** with an `Error` in these cases:
 
@@ -93,20 +99,20 @@ pompelmi.scan(filePath: string): Promise<"Clean" | "Malicious" | "ScanError">
 **Example — full error handling:**
 
 ```js
-const pompelmi = require('pompelmi');
+const { scan, Verdict } = require('pompelmi');
 const path = require('path');
 
 async function safeScan(filePath) {
   try {
-    const result = await pompelmi.scan(path.resolve(filePath));
+    const result = await scan(path.resolve(filePath));
 
-    if (result === 'ScanError') {
+    if (result === Verdict.ScanError) {
       // The scan could not complete — treat the file as untrusted.
       console.warn('Scan incomplete, rejecting file as precaution.');
       return null;
     }
 
-    return result; // "Clean" or "Malicious"
+    return result; // Verdict.Clean or Verdict.Malicious
   } catch (err) {
     console.error('Scan failed:', err.message);
     return null;
@@ -114,6 +120,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.
@@ -183,7 +204,7 @@ npm test
 
 The test suite has two parts:
 
-- **Unit tests** (`test/unit.test.js`) — run with Node's built-in test runner. Mock `cross-spawn` and platform dependencies; no ClamAV installation required.
+- **Unit tests** (`test/unit.test.js`) — run with Node's built-in test runner. Mock `nativeSpawn` from `src/spawn.js` and platform dependencies via require-cache injection; no ClamAV installation required.
 - **Integration tests** (`test/scan.test.js`) — spawn real `clamscan` processes against EICAR test files. Skipped automatically if `clamscan` is not found in PATH.
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.0.0",
+  "version": "1.2.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",
@@ -27,9 +27,7 @@
     "test": "node --test test/unit.test.js && node test/scan.test.js",
     "lint": "eslint src/"
   },
-  "dependencies": {
-    "cross-spawn": "^7.0.6"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.2.0",

package/src/ClamAVDatabaseUpdater.js

@@ -1,4 +1,4 @@
-const spawn = require("cross-spawn");
+const { nativeSpawn: spawn } = require('./spawn.js');
 const fs = require("fs");
 const { getUpdaterCommand } = require('./InstallerCommand.js');
 const { PLATFORM } = require('./constants.js');

package/src/ClamAVInstaller.js

@@ -1,4 +1,4 @@
-const spawn = require("cross-spawn");
+const { nativeSpawn: spawn } = require('./spawn.js');
 const { execSync } = require("child_process");
 const { getInstallerCommand } = require('./InstallerCommand.js');
 const { PLATFORM } = require('./constants.js')

package/src/ClamAVScanner.js

@@ -1,6 +1,7 @@
-const spawn = require("cross-spawn");
+const { nativeSpawn: spawn } = require('./spawn.js');
 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,82 @@
+'use strict';
+
+const net            = require('net');
+const fs             = require('fs');
+const { Verdict }    = require('./verdicts.js');
+
+// 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 Verdict.Clean;
+    if (text.endsWith(' FOUND'))  return Verdict.Malicious;
+    return Verdict.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/src/config.js

@@ -1,3 +1,5 @@
+const { Verdict } = require('./verdicts.js');
+
 module.exports = Object.freeze({
     INSTALLER_COMMANDS: Object.freeze({
         win32:  ['choco',  ['install', 'clamav', '-y']],
@@ -15,8 +17,8 @@ module.exports = Object.freeze({
         win32:  'C:\\ProgramData\\ClamAV\\main.cvd',
     }),
     SCAN_RESULTS: Object.freeze({
-        0: 'Clean',
-        1: 'Malicious',
-        2: 'ScanError'
+        0: Verdict.Clean,
+        1: Verdict.Malicious,
+        2: Verdict.ScanError,
     }),
 });

package/src/index.js

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

package/src/spawn.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+/**
+ * A thin wrapper around Node's built-in child_process.spawn that handles the
+ * one meaningful cross-platform difference: on Windows, .cmd/.bat launchers
+ * (e.g. choco, npm) cannot be resolved without the shell, so shell:true is
+ * required.  On POSIX systems the shell is never involved.
+ *
+ * All callers in this codebase pass only hardcoded, trusted arguments, so
+ * enabling the shell on Windows introduces no injection risk.
+ *
+ * @param {string}   cmd
+ * @param {string[]} args
+ * @param {object}   [options] - Passed through to child_process.spawn.
+ *                               `shell` is always overridden by this wrapper.
+ * @returns {import('child_process').ChildProcess}
+ */
+function nativeSpawn(cmd, args, options) {
+    return spawn(cmd, args, {
+        ...options,
+        shell: process.platform === 'win32',
+    });
+}
+
+module.exports = { nativeSpawn };

package/src/verdicts.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * Opaque Symbol-based scan verdicts.
+ *
+ * Using Symbols instead of strings makes comparisons typo-proof: a misspelled
+ * string silently produces `false`; an unknown Symbol property is `undefined`
+ * and fails loudly at the point of use.
+ *
+ * Usage:
+ *   const { Verdict } = require('pompelmi');
+ *   const result = await pompelmi.scan(filePath);
+ *   if (result === Verdict.Clean)     { /* safe *\/ }
+ *   if (result === Verdict.Malicious) { /* quarantine or reject *\/ }
+ *   if (result === Verdict.ScanError) { /* clamscan returned exit code 2 *\/ }
+ */
+const Verdict = Object.freeze({
+    Clean:     Symbol('Clean'),
+    Malicious: Symbol('Malicious'),
+    ScanError: Symbol('ScanError'),
+});
+
+module.exports = { Verdict };

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