pompelmi 1.18.0 → 1.19.0

package/README.md

@@ -11,7 +11,7 @@
 <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="weekly downloads"></a>
-  <a href="https://hub.docker.com/r/pompelmi/scanner"><img src="https://img.shields.io/docker/pulls/pompelmi/scanner" alt="Docker Pulls"></a>
+  <a href="https://hub.docker.com/r/justsouichi/pompelmi-scanner"><img src="https://img.shields.io/docker/pulls/justsouichi/pompelmi-scanner" alt="Docker Pulls"></a>
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
   <img src="https://img.shields.io/badge/license-ISC-blue" alt="license">
   <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml"><img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -74,7 +74,7 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 ## Features
 
 - Standalone CLI — scan files from any terminal with `npx pompelmi scan`
-- **Official Docker image** — `pompelmi/scanner` on Docker Hub: ClamAV + HTTP scan API in one pull ([docs](./docs/docker-image.html))
+- **Official Docker image** — `justsouichi/pompelmi-scanner` on Docker Hub: ClamAV + HTTP scan API in one pull ([docs](./docs/docker-image.html))
 - **Security scorecard** — grade your upload security A–F with `npx pompelmi scorecard` ([docs](./docs/scorecard.html))
 - **VS Code extension** — scan files directly from the IDE (scaffold in `packages/vscode/`) ([docs](./docs/vscode.html))
 - **Quarantine mode** — `watch ./uploads --quarantine ./quarantine` auto-moves infected files with sidecar JSON
@@ -90,6 +90,10 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - `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
+- **SHA256 scan cache** — `createCache([options])` — skip rescanning known-clean files; LRU eviction, configurable TTL, optional file-backed persistence; zero extra dependencies ([docs](./docs/cache.html))
+- **Scan policies** — `createPolicy(rules)` — unified size, MIME type, extension, and virus rules in one object; Express middleware and NestJS guard included ([docs](./docs/policy.html))
+- **Multi-engine scanning** — `createMultiEngine(options)` — combine ClamAV and VirusTotal with `any`/`all`/`majority` consensus; per-engine verdict breakdown; zero extra dependencies ([docs](./docs/multi-engine.html))
+- **Directory streaming** — `scanDirectory.stream(dirPath)` — async-iterable progress events (`progress` / `result` / `complete`) for real-time UI feedback
 - 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
@@ -622,6 +626,8 @@ Please read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing. To r
 - [x] Cloudflare Workers support — `@pompelmi/cloudflare` ships in v1.17.0
 - [x] NestJS official module — `PompelmiModule.forRoot()` with injectable `PompelmiService`
 
+**Pompelmi Cloud** is on the horizon — a hosted REST API for file scanning with zero infrastructure to manage. Drop-in HTTP endpoint, no ClamAV to maintain, no daemon to run. [Join the waitlist](https://pompelmi.app/cloud.html) to be notified when it launches.
+
 ---
 
 ## License

package/docker/README.md

@@ -1,4 +1,4 @@
-# pompelmi/scanner Docker Image
+# justsouichi/pompelmi-scanner Docker Image
 
 Official Docker image for pompelmi — ClamAV antivirus scanning for Node.js.
 
@@ -10,8 +10,8 @@ The image ships with:
 ## Quick start
 
 ```bash
-docker pull pompelmi/scanner
-docker run -p 8080:8080 pompelmi/scanner
+docker pull justsouichi/pompelmi-scanner
+docker run -p 8080:8080 justsouichi/pompelmi-scanner
 ```
 
 ## Scan a file
@@ -41,7 +41,7 @@ For an infected file the verdict is `"malicious"`.
 ```yaml
 services:
   pompelmi:
-    image: pompelmi/scanner
+    image: justsouichi/pompelmi-scanner
     ports:
       - "8080:8080"
     volumes:
@@ -58,5 +58,5 @@ The container exposes two ports:
 ## Building locally
 
 ```bash
-docker build -f docker/Dockerfile -t pompelmi/scanner .
+docker build -f docker/Dockerfile -t justsouichi/pompelmi-scanner .
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.18.0",
+  "version": "1.19.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/packages/vscode/README.md

@@ -51,7 +51,7 @@ Run `pompelmi: Configure` from the Command Palette to open settings.
 Start clamd via the official pompelmi Docker image:
 
 ```bash
-docker run -p 3310:3310 -p 8080:8080 pompelmi/scanner
+docker run -p 3310:3310 -p 8080:8080 justsouichi/pompelmi-scanner
 ```
 
 Then set `pompelmi.host` to `localhost` and `pompelmi.port` to `3310`.

package/src/ClamAVScanner.js

@@ -137,4 +137,44 @@ async function scanDirectory(dirPath, options = {}) {
     return { clean, malicious, errors };
 }
 
+async function* streamDirectory(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 total   = files.length;
+    let   scanned = 0;
+    const summary = { clean: [], malicious: [], errors: [] };
+
+    for (const filePath of files) {
+        let verdict;
+        try {
+            verdict = await scan(filePath, options);
+        } catch {
+            verdict = null;
+        }
+
+        scanned++;
+
+        if (verdict === Verdict.Clean)          summary.clean.push(filePath);
+        else if (verdict === Verdict.Malicious) summary.malicious.push(filePath);
+        else                                    summary.errors.push(filePath);
+
+        yield { type: 'progress', scanned, total, file: filePath };
+        yield { type: 'result',   file: filePath, verdict };
+    }
+
+    yield { type: 'complete', summary };
+}
+
+scanDirectory.stream = streamDirectory;
+
 module.exports = { scan, scanBuffer, scanStream, scanDirectory };

package/src/MultiEngine.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const https  = require('https');
+const http   = require('http');
+const crypto = require('crypto');
+const fs     = require('fs');
+const { scan, scanBuffer } = require('./ClamAVScanner.js');
+const { Verdict }          = require('./verdicts.js');
+
+// ── VirusTotal helpers ──────────────────────────────────────────────────────
+
+function vtRequest(method, urlStr, headers, body) {
+    return new Promise((resolve, reject) => {
+        const url  = new URL(urlStr);
+        const mod  = url.protocol === 'https:' ? https : http;
+        const opts = {
+            method,
+            hostname: url.hostname,
+            path:     url.pathname + url.search,
+            headers,
+        };
+        const req = mod.request(opts, (res) => {
+            const chunks = [];
+            res.on('data', c => chunks.push(c));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString()));
+                } catch {
+                    resolve({});
+                }
+            });
+        });
+        req.on('error', reject);
+        if (body) req.write(body);
+        req.end();
+    });
+}
+
+// Multipart form-data upload for VirusTotal /files endpoint
+function vtUpload(apiKey, buffer) {
+    return new Promise((resolve, reject) => {
+        const boundary = crypto.randomBytes(16).toString('hex');
+        const CRLF     = '\r\n';
+        const pre  = Buffer.from(
+            `--${boundary}${CRLF}` +
+            `Content-Disposition: form-data; name="file"; filename="upload"${CRLF}` +
+            `Content-Type: application/octet-stream${CRLF}${CRLF}`
+        );
+        const post = Buffer.from(`${CRLF}--${boundary}--${CRLF}`);
+        const body = Buffer.concat([pre, buffer, post]);
+
+        const opts = {
+            method:   'POST',
+            hostname: 'www.virustotal.com',
+            path:     '/api/v3/files',
+            headers:  {
+                'x-apikey':       apiKey,
+                'Content-Type':   `multipart/form-data; boundary=${boundary}`,
+                'Content-Length': body.length,
+            },
+        };
+
+        const req = https.request(opts, (res) => {
+            const chunks = [];
+            res.on('data', c => chunks.push(c));
+            res.on('end', () => {
+                try { resolve(JSON.parse(Buffer.concat(chunks).toString())); }
+                catch { resolve({}); }
+            });
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+
+async function vtScanBuffer(apiKey, buffer, threshold = 1) {
+    try {
+        // Upload file
+        const upload = await vtUpload(apiKey, buffer);
+        const id     = upload && upload.data && upload.data.id;
+        if (!id) return { name: 'virustotal', verdict: Verdict.ScanError, detections: 0, error: 'no analysis id' };
+
+        // Poll for result (up to 60s)
+        for (let i = 0; i < 12; i++) {
+            await new Promise(r => setTimeout(r, 5000));
+            const report = await vtRequest('GET',
+                `https://www.virustotal.com/api/v3/analyses/${id}`,
+                { 'x-apikey': apiKey }, null
+            );
+            const status = report && report.data && report.data.attributes && report.data.attributes.status;
+            if (status === 'completed') {
+                const stats      = report.data.attributes.stats || {};
+                const detections = (stats.malicious || 0) + (stats.suspicious || 0);
+                const verdict    = detections >= threshold ? Verdict.Malicious : Verdict.Clean;
+                return { name: 'virustotal', verdict, detections };
+            }
+        }
+        return { name: 'virustotal', verdict: Verdict.ScanError, detections: 0, error: 'timeout' };
+    } catch (err) {
+        return { name: 'virustotal', verdict: Verdict.ScanError, detections: 0, error: err.message };
+    }
+}
+
+// ── ClamAV engine wrapper ───────────────────────────────────────────────────
+
+async function clamavScanFile(config, filePath) {
+    try {
+        const verdict = await scan(filePath, config);
+        return { name: 'clamav', verdict };
+    } catch (err) {
+        return { name: 'clamav', verdict: Verdict.ScanError, error: err.message };
+    }
+}
+
+async function clamavScanBuffer(config, buffer) {
+    try {
+        const verdict = await scanBuffer(buffer, config);
+        return { name: 'clamav', verdict };
+    } catch (err) {
+        return { name: 'clamav', verdict: Verdict.ScanError, error: err.message };
+    }
+}
+
+// ── Consensus logic ─────────────────────────────────────────────────────────
+
+function applyConsensus(results, consensus) {
+    const verdicts = results.map(r => r.verdict);
+    const malCount = verdicts.filter(v => v === Verdict.Malicious).length;
+    const total    = verdicts.length;
+
+    let final;
+    if (consensus === 'all') {
+        final = malCount === total ? Verdict.Malicious : Verdict.Clean;
+    } else if (consensus === 'majority') {
+        final = malCount > total / 2 ? Verdict.Malicious : Verdict.Clean;
+    } else {
+        // 'any' (default)
+        final = malCount > 0 ? Verdict.Malicious : Verdict.Clean;
+    }
+
+    // If no conclusive result but errors exist, propagate ScanError
+    if (final === Verdict.Clean && verdicts.every(v => v === Verdict.ScanError)) {
+        final = Verdict.ScanError;
+    }
+
+    return final;
+}
+
+// ── Public factory ──────────────────────────────────────────────────────────
+
+function createMultiEngine(config = {}) {
+    const { engines = [], consensus = 'any' } = config;
+
+    async function _runEnginesOnBuffer(buffer) {
+        return Promise.all(engines.map(async (engine) => {
+            if (engine.type === 'virustotal') {
+                if (!engine.apiKey) return { name: 'virustotal', verdict: Verdict.ScanError, error: 'no apiKey' };
+                return vtScanBuffer(engine.apiKey, buffer, engine.threshold ?? 1);
+            }
+            // clamav
+            return clamavScanBuffer(engine, buffer);
+        }));
+    }
+
+    async function scanMultiBuffer(buffer) {
+        if (!Buffer.isBuffer(buffer)) throw new Error('buffer must be a Buffer');
+        const engineResults = await _runEnginesOnBuffer(buffer);
+        const verdict = applyConsensus(engineResults, consensus);
+        return { verdict, consensus, engines: engineResults };
+    }
+
+    async function scanMultiFile(filePath) {
+        if (typeof filePath !== 'string') throw new Error('filePath must be a string');
+        const buffer = fs.readFileSync(filePath);
+        const engineResults = await Promise.all(engines.map(async (engine) => {
+            if (engine.type === 'virustotal') {
+                if (!engine.apiKey) return { name: 'virustotal', verdict: Verdict.ScanError, error: 'no apiKey' };
+                return vtScanBuffer(engine.apiKey, buffer, engine.threshold ?? 1);
+            }
+            return clamavScanFile(engine, filePath);
+        }));
+        const verdict = applyConsensus(engineResults, consensus);
+        return { verdict, consensus, engines: engineResults };
+    }
+
+    return { scan: scanMultiFile, scanBuffer: scanMultiBuffer };
+}
+
+module.exports = { createMultiEngine };

package/src/Policy.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const path = require('path');
+const { scanBuffer } = require('./ClamAVScanner.js');
+const { Verdict }    = require('./verdicts.js');
+
+const REASONS = {
+    FILE_TOO_LARGE:      'file_too_large',
+    MIME_NOT_ALLOWED:    'mime_not_allowed',
+    EXT_NOT_ALLOWED:     'extension_not_allowed',
+    ENCRYPTED:           'encrypted_archive',
+    VIRUS_DETECTED:      'virus_detected',
+    SCANNER_UNAVAILABLE: 'scanner_unavailable',
+};
+
+// Minimal magic-byte check for encrypted ZIP (central directory encrypted flag)
+function looksEncrypted(buffer) {
+    // ZIP local file header signature: 50 4B 03 04
+    // General-purpose bit flag word at offset 6; bit 0 = encryption
+    if (buffer.length < 8) return false;
+    if (buffer[0] === 0x50 && buffer[1] === 0x4B &&
+        buffer[2] === 0x03 && buffer[3] === 0x04) {
+        const flags = buffer.readUInt16LE(6);
+        return (flags & 0x01) !== 0;
+    }
+    return false;
+}
+
+function createPolicy(rules = {}) {
+    const {
+        scan: scanOpts           = undefined,
+        maxSize                  = null,
+        allowedMimeTypes         = null,
+        allowedExtensions        = null,
+        rejectEncrypted          = false,
+        onScannerUnavailable     = 'reject',
+    } = rules;
+
+    async function check(buffer, meta = {}) {
+        const { filename = null, mimeType = null, size = buffer.length } = meta;
+        const details = { size, mimeType, extension: null, virusName: null };
+
+        if (filename) {
+            details.extension = path.extname(filename).toLowerCase();
+        }
+
+        // 1. Size check
+        if (maxSize !== null && size > maxSize) {
+            return { allowed: false, reason: REASONS.FILE_TOO_LARGE, verdict: Verdict.ScanError, details };
+        }
+
+        // 2. MIME type check
+        if (allowedMimeTypes && mimeType) {
+            if (!allowedMimeTypes.includes(mimeType)) {
+                return { allowed: false, reason: REASONS.MIME_NOT_ALLOWED, verdict: Verdict.ScanError, details };
+            }
+        }
+
+        // 3. Extension check
+        if (allowedExtensions && details.extension) {
+            if (!allowedExtensions.includes(details.extension)) {
+                return { allowed: false, reason: REASONS.EXT_NOT_ALLOWED, verdict: Verdict.ScanError, details };
+            }
+        }
+
+        // 4. Encrypted archive check
+        if (rejectEncrypted && looksEncrypted(buffer)) {
+            return { allowed: false, reason: REASONS.ENCRYPTED, verdict: Verdict.ScanError, details };
+        }
+
+        // 5. Virus scan
+        if (scanOpts !== undefined) {
+            let verdict;
+            try {
+                verdict = await scanBuffer(buffer, scanOpts);
+            } catch (err) {
+                if (onScannerUnavailable === 'allow') {
+                    return { allowed: true, reason: null, verdict: Verdict.ScanError, details };
+                }
+                if (onScannerUnavailable === 'throw') {
+                    throw err;
+                }
+                // 'reject'
+                return { allowed: false, reason: REASONS.SCANNER_UNAVAILABLE, verdict: Verdict.ScanError, details };
+            }
+
+            if (verdict === Verdict.Malicious) {
+                return { allowed: false, reason: REASONS.VIRUS_DETECTED, verdict: Verdict.Malicious, details };
+            }
+
+            return { allowed: true, reason: null, verdict, details };
+        }
+
+        return { allowed: true, reason: null, verdict: Verdict.Clean, details };
+    }
+
+    function middleware() {
+        return async function policyMiddleware(req, res, next) {
+            let file = null;
+            if (req.file) {
+                file = req.file;
+            } else if (req.files) {
+                const files = Array.isArray(req.files)
+                    ? req.files
+                    : Object.values(req.files).flat();
+                file = files[0] || null;
+            }
+
+            if (!file) return next();
+
+            const buffer   = file.buffer;
+            const filename = file.originalname || null;
+            const mimeType = file.mimetype || null;
+            const size     = buffer ? buffer.length : (file.size || 0);
+
+            try {
+                const result = await check(buffer || Buffer.alloc(0), { filename, mimeType, size });
+                if (!result.allowed) {
+                    return res.status(403).json({ error: result.reason });
+                }
+                next();
+            } catch (err) {
+                next(err);
+            }
+        };
+    }
+
+    function nestGuard() {
+        return {
+            canActivate: async (context) => {
+                const req    = context.switchToHttp().getRequest();
+                const res    = context.switchToHttp().getResponse();
+                const file   = req.file || (req.files && (Array.isArray(req.files) ? req.files[0] : Object.values(req.files).flat()[0]));
+                if (!file) return true;
+
+                const buffer   = file.buffer;
+                const filename = file.originalname || null;
+                const mimeType = file.mimetype || null;
+                const size     = buffer ? buffer.length : (file.size || 0);
+
+                const result = await check(buffer || Buffer.alloc(0), { filename, mimeType, size });
+                if (!result.allowed) {
+                    res.status(403).json({ error: result.reason });
+                    return false;
+                }
+                return true;
+            },
+        };
+    }
+
+    return { check, middleware, nestGuard };
+}
+
+module.exports = { createPolicy };

package/src/ScanCache.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs     = require('fs');
+const { scan, scanBuffer } = require('./ClamAVScanner.js');
+
+function sha256ofBuffer(buf) {
+    return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function sha256ofFile(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto.createHash('sha256');
+        const stream = fs.createReadStream(filePath);
+        stream.on('error', reject);
+        stream.on('data', chunk => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+    });
+}
+
+function createCache(options = {}) {
+    const ttl      = options.ttl      ?? 3600000;
+    const maxSize  = options.maxSize  ?? 1000;
+    const storage  = options.storage  || 'memory';
+    const filePath = options.filePath || './.pompelmi-cache.json';
+
+    // LRU map: key = sha256, value = { verdict, expiresAt }
+    // Insertion order tracks LRU; on hit we re-insert to move to back.
+    let store = new Map();
+    let hits   = 0;
+    let misses = 0;
+    let writeTimer = null;
+
+    // ── file storage bootstrap ──────────────────────────────────────────────────
+    if (storage === 'file') {
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            const now = Date.now();
+            for (const [k, v] of Object.entries(raw)) {
+                if (v.expiresAt > now) store.set(k, v);
+            }
+        } catch {
+            // file absent or invalid — start with empty cache
+        }
+    }
+
+    function _persist() {
+        if (storage !== 'file') return;
+        if (writeTimer) return;
+        writeTimer = setTimeout(() => {
+            writeTimer = null;
+            const obj = {};
+            for (const [k, v] of store) obj[k] = v;
+            const tmp = filePath + '.tmp';
+            try {
+                fs.writeFileSync(tmp, JSON.stringify(obj));
+                fs.renameSync(tmp, filePath);
+            } catch { /* non-fatal */ }
+        }, 500);
+    }
+
+    function _get(sha) {
+        const entry = store.get(sha);
+        if (!entry) return null;
+        if (Date.now() > entry.expiresAt) {
+            store.delete(sha);
+            return null;
+        }
+        // Move to end (LRU: most-recently-used = last)
+        store.delete(sha);
+        store.set(sha, entry);
+        return entry.verdict;
+    }
+
+    function _set(sha, verdict) {
+        if (store.has(sha)) store.delete(sha); // re-insert at end
+        if (store.size >= maxSize) {
+            // evict oldest (first) entry
+            store.delete(store.keys().next().value);
+        }
+        store.set(sha, { verdict, expiresAt: Date.now() + ttl });
+        _persist();
+    }
+
+    async function scanWithCache(filePath, opts = {}) {
+        const sha = await sha256ofFile(filePath);
+        const cached = _get(sha);
+        if (cached !== null) { hits++; return cached; }
+        misses++;
+        const verdict = await scan(filePath, opts);
+        _set(sha, verdict);
+        return verdict;
+    }
+
+    async function scanBufferWithCache(buffer, opts = {}) {
+        const sha = sha256ofBuffer(buffer);
+        const cached = _get(sha);
+        if (cached !== null) { hits++; return cached; }
+        misses++;
+        const verdict = await scanBuffer(buffer, opts);
+        _set(sha, verdict);
+        return verdict;
+    }
+
+    function stats() {
+        const total = hits + misses;
+        return {
+            hits,
+            misses,
+            size: store.size,
+            hitRate: total === 0 ? 0 : hits / total,
+        };
+    }
+
+    function clear() {
+        store = new Map();
+        hits = 0;
+        misses = 0;
+        _persist();
+    }
+
+    function del(sha) {
+        store.delete(sha);
+        _persist();
+    }
+
+    return {
+        scan:        scanWithCache,
+        scanBuffer:  scanBufferWithCache,
+        stats,
+        clear,
+        delete:      del,
+    };
+}
+
+module.exports = { createCache };

package/src/index.js

@@ -9,5 +9,8 @@ const { createScanner }                               = require('./ScanEmitter.j
 const { generateDashboard }                           = require('./Dashboard.js');
 const { generateShareCard }                           = require('./ShareCard.js');
 const { generateScorecard }                           = require('./Scorecard.js');
+const { createCache }                                 = require('./ScanCache.js');
+const { createPolicy }                                = require('./Policy.js');
+const { createMultiEngine }                           = require('./MultiEngine.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner, generateDashboard, generateShareCard, generateScorecard };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner, generateDashboard, generateShareCard, generateScorecard, createCache, createPolicy, createMultiEngine };

package/src/index.mjs

@@ -13,7 +13,11 @@ export const {
   createScanner,
   generateDashboard,
   generateShareCard,
+  generateScorecard,
   notify,
   Verdict,
+  createCache,
+  createPolicy,
+  createMultiEngine,
 } = pompelmi;
 export default pompelmi;

package/types/index.d.ts

@@ -73,11 +73,14 @@ export declare function scanStream(stream: Readable, options?: ScanOptions): Pro
 /**
  * Recursively scan every file under dirPath.
  * Per-file errors are caught and collected without aborting the full scan.
+ * Use scanDirectory.stream() for async-iterable progress events.
  */
 export declare function scanDirectory(
   dirPath: string,
   options?: ScanOptions
-): Promise<DirectoryScanResult>;
+): Promise<DirectoryScanResult> & {
+  stream(dirPath: string, options?: ScanOptions): AsyncIterable<DirectoryScanEvent>;
+};
 
 /**
  * Express / Fastify middleware that scans multer-uploaded files
@@ -328,3 +331,190 @@ export interface ScorecardResult {
  * console.log(scorecard.grade); // 'A'
  */
 export declare function generateScorecard(config?: ScorecardConfig): Promise<ScorecardResult>;
+
+// ─── ScanCache ────────────────────────────────────────────────────────────────
+
+/** Options for createCache() */
+export interface CacheOptions {
+  /** Entry TTL in milliseconds (default: 3600000 = 1 hour) */
+  ttl?: number;
+  /** Maximum number of entries before LRU eviction (default: 1000) */
+  maxSize?: number;
+  /** Storage backend: 'memory' or 'file' (default: 'memory') */
+  storage?: 'memory' | 'file';
+  /** Path for file-backed storage (default: './.pompelmi-cache.json') */
+  filePath?: string;
+}
+
+/** Cache hit/miss statistics */
+export interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  hitRate: number;
+}
+
+/** SHA256-based scan result cache */
+export interface ScanCache {
+  /** Scan a file by path, returning a cached result if available */
+  scan(filePath: string, options?: ScanOptions): Promise<VerdictValue>;
+  /** Scan an in-memory Buffer, returning a cached result if available */
+  scanBuffer(buffer: Buffer, options?: ScanOptions): Promise<VerdictValue>;
+  /** Return cache statistics */
+  stats(): CacheStats;
+  /** Clear all cache entries */
+  clear(): void;
+  /** Remove a specific entry by its SHA256 hash */
+  delete(sha256: string): void;
+}
+
+/**
+ * Create a SHA256-based scan result cache.
+ * Skips rescanning files with known-clean or known-malicious hashes.
+ * Supports LRU eviction and optional file-backed persistence.
+ */
+export declare function createCache(options?: CacheOptions): ScanCache;
+
+// ─── Policy ───────────────────────────────────────────────────────────────────
+
+/** Options for createPolicy() */
+export interface PolicyRules {
+  /** ClamAV connection options for virus scanning */
+  scan?: ScanOptions;
+  /** Maximum allowed file size in bytes */
+  maxSize?: number;
+  /** Allowlist of MIME types (e.g. ['image/jpeg', 'application/pdf']) */
+  allowedMimeTypes?: string[];
+  /** Allowlist of file extensions (e.g. ['.jpg', '.pdf']) */
+  allowedExtensions?: string[];
+  /** Reject encrypted archives (default: false) */
+  rejectEncrypted?: boolean;
+  /** Behaviour when clamd is unavailable: 'reject' | 'allow' | 'throw' (default: 'reject') */
+  onScannerUnavailable?: 'reject' | 'allow' | 'throw';
+}
+
+/** Metadata passed to policy.check() */
+export interface FileMeta {
+  filename?: string | null;
+  mimeType?: string | null;
+  size?: number;
+}
+
+/** Details about the file that was checked */
+export interface PolicyDetails {
+  size: number;
+  mimeType: string | null;
+  extension: string | null;
+  virusName: string | null;
+}
+
+/** Result returned by policy.check() */
+export interface PolicyResult {
+  allowed: boolean;
+  reason:
+    | null
+    | 'file_too_large'
+    | 'mime_not_allowed'
+    | 'extension_not_allowed'
+    | 'encrypted_archive'
+    | 'virus_detected'
+    | 'scanner_unavailable';
+  verdict: VerdictValue;
+  details: PolicyDetails;
+}
+
+/** A compiled scan policy */
+export interface ScanPolicy {
+  /** Apply all policy rules to a buffer */
+  check(buffer: Buffer, meta?: FileMeta): Promise<PolicyResult>;
+  /** Express/Fastify middleware — rejects with HTTP 403 on policy violation */
+  middleware(): RequestHandler;
+  /** NestJS CanActivate guard */
+  nestGuard(): { canActivate(context: unknown): Promise<boolean> };
+}
+
+/**
+ * Create a unified scan policy combining size, MIME, extension, and virus checks.
+ */
+export declare function createPolicy(rules?: PolicyRules): ScanPolicy;
+
+// ─── MultiEngine ─────────────────────────────────────────────────────────────
+
+/** ClamAV engine configuration */
+export interface ClamAVEngineConfig {
+  type: 'clamav';
+  host?: string;
+  port?: number;
+  socket?: string;
+  timeout?: number;
+}
+
+/** VirusTotal engine configuration */
+export interface VirusTotalEngineConfig {
+  type: 'virustotal';
+  apiKey: string;
+  /** Minimum number of engine detections to flag as malicious (default: 1) */
+  threshold?: number;
+}
+
+export type EngineConfig = ClamAVEngineConfig | VirusTotalEngineConfig;
+
+/** Per-engine result */
+export interface EngineResult {
+  name: string;
+  verdict: VerdictValue;
+  detections?: number;
+  virus?: string;
+  error?: string;
+}
+
+/** Result returned by multi-engine scan */
+export interface MultiEngineResult {
+  verdict: VerdictValue;
+  consensus: 'any' | 'all' | 'majority';
+  engines: EngineResult[];
+}
+
+/** Options for createMultiEngine() */
+export interface MultiEngineOptions {
+  engines: EngineConfig[];
+  /** How to combine engine verdicts (default: 'any') */
+  consensus?: 'any' | 'all' | 'majority';
+}
+
+/** Multi-engine scanner */
+export interface MultiEngine {
+  scan(filePath: string): Promise<MultiEngineResult>;
+  scanBuffer(buffer: Buffer): Promise<MultiEngineResult>;
+}
+
+/**
+ * Create a multi-engine scanner combining ClamAV and/or VirusTotal.
+ * The consensus mode controls how engine verdicts are combined.
+ */
+export declare function createMultiEngine(options?: MultiEngineOptions): MultiEngine;
+
+// ─── scanDirectory.stream ─────────────────────────────────────────────────────
+
+/** Progress event emitted by scanDirectory.stream() */
+export interface ScanProgressEvent {
+  type: 'progress';
+  scanned: number;
+  total: number;
+  file: string;
+}
+
+/** Per-file result event emitted by scanDirectory.stream() */
+export interface ScanResultEvent {
+  type: 'result';
+  file: string;
+  verdict: VerdictValue | null;
+}
+
+/** Final summary event emitted by scanDirectory.stream() */
+export interface ScanCompleteEvent {
+  type: 'complete';
+  summary: DirectoryScanResult;
+}
+
+export type DirectoryScanEvent = ScanProgressEvent | ScanResultEvent | ScanCompleteEvent;