pompelmi 1.10.0 → 1.11.0

package/.mailmap

@@ -0,0 +1,3 @@
+JustSouichi <tommasobertocchideveloper04@gmail.com> claude <claude@anthropic.com>
+JustSouichi <tommasobertocchideveloper04@gmail.com> Claude <claude@anthropic.com>
+JustSouichi <tommasobertocchideveloper04@gmail.com> Claude Code <noreply@anthropic.com>

package/README.md

@@ -63,6 +63,8 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - `scanS3(params, [options])` — scan S3 objects by streaming directly from AWS S3, no disk I/O
 - `createPool([options])` — persistent connection pool for high-throughput clamd scanning
 - `watch(dirPath, [options], callbacks)` — watch a directory and auto-scan new/modified files (300 ms debounce)
+- `notify(webhookUrl, scanResult, [options])` — send a POST webhook notification when a virus is detected; optional HMAC-SHA256 signing via `X-Pompelmi-Signature`; zero extra dependencies
+- `createScanner([options])` — EventEmitter-based scanner; call `.scan(filePath)` or `.scanDirectory(dirPath)` and listen to `'clean'`, `'malicious'`, `'scanError'`, and `'error'` events
 - Auto-retry on connection error — `retries` and `retryDelay` options on every scan function
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
 - Full clamd support via the INSTREAM protocol — TCP (`host`/`port`) or UNIX socket (`socket`) with configurable timeout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.10.0",
+  "version": "1.11.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/ScanEmitter.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const path = require('path');
+const fs   = require('fs');
+const { scan } = require('./ClamAVScanner.js');
+const { Verdict } = require('./verdicts.js');
+
+/**
+ * Returns an EventEmitter-based scanner.
+ *
+ * Events:
+ *   'clean'     (filePath)           — file scanned clean
+ *   'malicious' (filePath, viruses)  — virus detected (viruses is always [])
+ *   'error'     (err)                — unexpected error (not a scan verdict)
+ *   'scanError' (filePath)           — scan returned Verdict.ScanError
+ *
+ * @param {object} [options] - ScanOptions forwarded to scan()
+ * @returns {EventEmitter & { scan(filePath): void, scanDirectory(dirPath): void }}
+ */
+function createScanner(options = {}) {
+    const emitter = new EventEmitter();
+
+    /**
+     * Scan a single file and emit the appropriate event.
+     * @param {string} filePath
+     */
+    emitter.scan = function scanFile(filePath) {
+        scan(filePath, options)
+            .then((verdict) => {
+                if (verdict === Verdict.Clean) {
+                    emitter.emit('clean', filePath);
+                } else if (verdict === Verdict.Malicious) {
+                    emitter.emit('malicious', filePath, []);
+                } else {
+                    emitter.emit('scanError', filePath);
+                }
+            })
+            .catch((err) => {
+                emitter.emit('error', err);
+            });
+    };
+
+    /**
+     * Recursively scan every file in dirPath and emit events per file.
+     * @param {string} dirPath
+     */
+    emitter.scanDirectory = function scanDir(dirPath) {
+        if (!fs.existsSync(dirPath)) {
+            emitter.emit('error', new Error(`Directory not found: ${dirPath}`));
+            return;
+        }
+
+        let files;
+        try {
+            files = fs.readdirSync(dirPath);
+        } catch (err) {
+            emitter.emit('error', err);
+            return;
+        }
+
+        for (const file of files) {
+            const fullPath = path.join(dirPath, file);
+            let stat;
+            try {
+                stat = fs.statSync(fullPath);
+            } catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                emitter.scanDirectory(fullPath);
+            } else {
+                emitter.scan(fullPath);
+            }
+        }
+    };
+
+    return emitter;
+}
+
+module.exports = { createScanner };

package/src/WebhookNotifier.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const https = require('https');
+const http  = require('http');
+const crypto = require('crypto');
+const os     = require('os');
+const { URL } = require('url');
+
+/**
+ * Send a POST webhook notification when a scan result is available.
+ *
+ * @param {string} webhookUrl - Destination URL (http or https).
+ * @param {object} scanResult - { file, verdict, viruses }
+ * @param {object} [options]  - { onlyOnMalicious, secret }
+ * @returns {Promise<void>}
+ */
+function notify(webhookUrl, scanResult, options = {}) {
+    const { onlyOnMalicious = true, secret } = options;
+
+    if (!webhookUrl || typeof webhookUrl !== 'string') {
+        return Promise.reject(new Error('webhookUrl must be a non-empty string'));
+    }
+    if (!scanResult || typeof scanResult !== 'object') {
+        return Promise.reject(new Error('scanResult must be an object'));
+    }
+
+    const verdictDescription =
+        scanResult.verdict && typeof scanResult.verdict === 'symbol'
+            ? scanResult.verdict.description
+            : String(scanResult.verdict ?? 'Unknown');
+
+    const isMalicious = verdictDescription === 'Malicious';
+
+    if (onlyOnMalicious && !isMalicious) {
+        return Promise.resolve();
+    }
+
+    const payload = JSON.stringify({
+        file:      scanResult.file ?? null,
+        verdict:   verdictDescription,
+        viruses:   scanResult.viruses ?? [],
+        timestamp: new Date().toISOString(),
+        hostname:  os.hostname(),
+    });
+
+    return new Promise((resolve, reject) => {
+        let parsed;
+        try {
+            parsed = new URL(webhookUrl);
+        } catch {
+            return reject(new Error(`Invalid webhookUrl: ${webhookUrl}`));
+        }
+
+        const isHttps = parsed.protocol === 'https:';
+        const transport = isHttps ? https : http;
+
+        const headers = {
+            'Content-Type':   'application/json',
+            'Content-Length': Buffer.byteLength(payload),
+            'User-Agent':     'pompelmi-webhook/1.0',
+        };
+
+        if (secret) {
+            const sig = crypto
+                .createHmac('sha256', secret)
+                .update(payload)
+                .digest('hex');
+            headers['X-Pompelmi-Signature'] = `sha256=${sig}`;
+        }
+
+        const reqOptions = {
+            hostname: parsed.hostname,
+            port:     parsed.port || (isHttps ? 443 : 80),
+            path:     parsed.pathname + parsed.search,
+            method:   'POST',
+            headers,
+        };
+
+        const req = transport.request(reqOptions, (res) => {
+            res.resume(); // drain response body
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+                resolve();
+            } else {
+                reject(new Error(`Webhook responded with HTTP ${res.statusCode}`));
+            }
+        });
+
+        req.on('error', reject);
+        req.write(payload);
+        req.end();
+    });
+}
+
+module.exports = { notify };

package/src/index.js

@@ -4,5 +4,7 @@ const { middleware }                                  = require('./middleware.js
 const { scanS3 }                                      = require('./S3Scanner.js');
 const { createPool }                                  = require('./ClamdPool.js');
 const { watch }                                       = require('./Watcher.js');
+const { notify }                                      = require('./WebhookNotifier.js');
+const { createScanner }                               = require('./ScanEmitter.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner };

package/types/index.d.ts

@@ -152,3 +152,66 @@ export declare function watch(
   options?: ScanOptions,
   callbacks?: WatchCallbacks
 ): FSWatcher;
+
+/** Payload sent by the webhook notifier */
+export interface WebhookPayload {
+  file: string | null;
+  verdict: string;
+  viruses: string[];
+  timestamp: string;
+  hostname: string;
+}
+
+/** Options for notify() */
+export interface NotifyOptions {
+  /** Only send a webhook when the verdict is Malicious (default: true) */
+  onlyOnMalicious?: boolean;
+  /** HMAC-SHA256 secret — adds X-Pompelmi-Signature header when set */
+  secret?: string;
+}
+
+/** scan result passed to notify() */
+export interface ScanResultInput {
+  file?: string | null;
+  verdict: symbol | string;
+  viruses?: string[];
+}
+
+/**
+ * Send a POST webhook notification for a scan result.
+ * Uses Node.js built-in https/http — no external dependencies.
+ * When secret is provided, adds an X-Pompelmi-Signature: sha256=<hmac> header.
+ */
+export declare function notify(
+  webhookUrl: string,
+  scanResult: ScanResultInput,
+  options?: NotifyOptions
+): Promise<void>;
+
+import { EventEmitter } from 'events';
+
+/** EventEmitter-based scanner returned by createScanner() */
+export interface ScanEmitter extends EventEmitter {
+  /** Scan a single file; emits 'clean', 'malicious', 'scanError', or 'error' */
+  scan(filePath: string): void;
+  /** Recursively scan every file in dirPath; emits per-file events */
+  scanDirectory(dirPath: string): void;
+
+  on(event: 'clean',     listener: (filePath: string) => void): this;
+  on(event: 'malicious', listener: (filePath: string, viruses: string[]) => void): this;
+  on(event: 'scanError', listener: (filePath: string) => void): this;
+  on(event: 'error',     listener: (err: Error) => void): this;
+  on(event: string,      listener: (...args: unknown[]) => void): this;
+}
+
+/**
+ * Create an EventEmitter-based scanner.
+ * Options are forwarded to the underlying scan() call (host, port, socket, etc.).
+ *
+ * @example
+ * const scanner = createScanner({ host: 'localhost', port: 3310 });
+ * scanner.on('malicious', (file, viruses) => console.log('VIRUS:', file));
+ * scanner.scan('file.pdf');
+ * scanner.scanDirectory('/uploads');
+ */
+export declare function createScanner(options?: ScanOptions): ScanEmitter;