pompelmi 1.5.0 → 1.6.0

package/wiki/typescript-usage.md

@@ -0,0 +1,239 @@
+# TypeScript Usage
+
+pompelmi ships CommonJS source without bundled `.d.ts` files. This page shows how to add inline type declarations and build typed wrappers for use in TypeScript projects.
+
+---
+
+## Inline type declaration (one file)
+
+Add a declaration block at the top of any `.ts` file that imports pompelmi:
+
+```ts
+declare module 'pompelmi' {
+  export interface ScanOptions {
+    host?: string;
+    port?: number;
+    timeout?: number;
+  }
+
+  export interface DirectoryScanResult {
+    clean: string[];
+    malicious: string[];
+    errors: string[];
+  }
+
+  export interface VerdictSymbols {
+    Clean: symbol;
+    Malicious: symbol;
+    ScanError: symbol;
+  }
+
+  export const Verdict: VerdictSymbols;
+
+  export function scan(filePath: string, options?: ScanOptions): Promise<symbol>;
+  export function scanBuffer(buffer: Buffer, options?: ScanOptions): Promise<symbol>;
+  export function scanStream(stream: import('stream').Readable, options?: ScanOptions): Promise<symbol>;
+  export function scanDirectory(dirPath: string, options?: ScanOptions): Promise<DirectoryScanResult>;
+}
+```
+
+---
+
+## Shared declaration file
+
+For projects with multiple files importing pompelmi, put the declaration in a `.d.ts` file:
+
+```ts
+// types/pompelmi.d.ts
+declare module 'pompelmi' {
+  export interface ScanOptions {
+    host?: string;
+    port?: number;
+    timeout?: number;
+  }
+
+  export interface DirectoryScanResult {
+    clean: string[];
+    malicious: string[];
+    errors: string[];
+  }
+
+  export interface VerdictSymbols {
+    readonly Clean: unique symbol;
+    readonly Malicious: unique symbol;
+    readonly ScanError: unique symbol;
+  }
+
+  export const Verdict: VerdictSymbols;
+  export function scan(filePath: string, options?: ScanOptions): Promise<symbol>;
+  export function scanBuffer(buffer: Buffer, options?: ScanOptions): Promise<symbol>;
+  export function scanStream(stream: import('stream').Readable, options?: ScanOptions): Promise<symbol>;
+  export function scanDirectory(dirPath: string, options?: ScanOptions): Promise<DirectoryScanResult>;
+}
+```
+
+Include it in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "typeRoots": ["./types", "./node_modules/@types"]
+  }
+}
+```
+
+---
+
+## Typed wrapper
+
+Wrap pompelmi in a typed service class for easier use across a NestJS or typed Express app:
+
+```ts
+// scan.service.ts
+import { scan, scanBuffer, scanStream, scanDirectory, Verdict, ScanOptions } from 'pompelmi';
+import { Readable } from 'stream';
+
+export type ScanVerdict = 'clean' | 'malicious' | 'error';
+
+export interface FileScanResult {
+  verdict: ScanVerdict;
+  description: string;
+}
+
+export interface DirectoryResult {
+  clean: string[];
+  malicious: string[];
+  errors: string[];
+}
+
+export class ScanService {
+  constructor(private readonly opts: ScanOptions = {}) {}
+
+  private mapVerdict(symbol: symbol): ScanVerdict {
+    if (symbol === Verdict.Clean)     return 'clean';
+    if (symbol === Verdict.Malicious) return 'malicious';
+    return 'error';
+  }
+
+  async scanFile(filePath: string): Promise<FileScanResult> {
+    const result = await scan(filePath, this.opts);
+    return { verdict: this.mapVerdict(result), description: (result as symbol & { description: string }).description };
+  }
+
+  async scanBuffer(buffer: Buffer): Promise<FileScanResult> {
+    const result = await scanBuffer(buffer, this.opts);
+    return { verdict: this.mapVerdict(result), description: (result as symbol & { description: string }).description };
+  }
+
+  async scanStream(stream: Readable): Promise<FileScanResult> {
+    const result = await scanStream(stream, this.opts);
+    return { verdict: this.mapVerdict(result), description: (result as symbol & { description: string }).description };
+  }
+
+  async scanDirectory(dirPath: string): Promise<DirectoryResult> {
+    return scanDirectory(dirPath, this.opts);
+  }
+}
+```
+
+---
+
+## Express with typed request handlers
+
+```ts
+import express, { Request, Response, NextFunction } from 'express';
+import multer from 'multer';
+import fs from 'fs';
+import { scan, Verdict } from 'pompelmi';
+
+const app    = express();
+const upload = multer({ dest: './uploads' });
+
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST,
+  port: Number(process.env.CLAMAV_PORT) || 3310,
+};
+
+app.post(
+  '/upload',
+  upload.single('file'),
+  async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    if (!req.file) {
+      res.status(400).json({ error: 'No file uploaded.' });
+      return;
+    }
+
+    try {
+      const result = await scan(req.file.path, SCAN_OPTS);
+
+      if (result !== Verdict.Clean) {
+        fs.unlinkSync(req.file.path);
+        res.status(422).json({ error: (result as { description: string }).description });
+        return;
+      }
+
+      res.json({ ok: true, filename: req.file.filename });
+    } catch (err: unknown) {
+      try { fs.unlinkSync(req.file.path); } catch {}
+      next(err);
+    }
+  }
+);
+```
+
+---
+
+## Strict null checks
+
+With `"strict": true` in `tsconfig.json`, guard against `undefined` file fields:
+
+```ts
+async function handleUpload(req: Request, res: Response): Promise<void> {
+  const file = req.file;
+  if (file === undefined) {
+    res.status(400).json({ error: 'No file.' });
+    return;
+  }
+
+  const result = await scan(file.path, SCAN_OPTS);
+
+  if (result === Verdict.Malicious) {
+    fs.unlinkSync(file.path);
+    res.status(422).json({ error: 'Malicious file rejected.' });
+    return;
+  }
+
+  res.json({ ok: true });
+}
+```
+
+---
+
+## `tsconfig.json` settings
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "typeRoots": ["./types", "./node_modules/@types"]
+  },
+  "include": ["src/**/*", "types/**/*"]
+}
+```
+
+---
+
+## Using with `ts-node`
+
+```bash
+npm install -D ts-node typescript @types/node @types/multer
+npx ts-node src/server.ts
+```
+
+No additional configuration is needed for pompelmi specifically.

package/wiki/verdicts.md

@@ -0,0 +1,192 @@
+# Verdicts
+
+pompelmi uses ES6 Symbols as return values instead of strings or numbers. This page explains why, how to compare them correctly, what each verdict means, and how to serialise them.
+
+---
+
+## Why Symbols instead of strings
+
+Strings are error-prone at the call site:
+
+```js
+// String-based API — these all silently fail
+if (result === 'clean') { }      // wrong case
+if (result === 'Clean ') { }     // trailing space
+if (result === 'CLEAN') { }      // wrong case
+```
+
+A Symbol comparison either matches exactly or it does not. There is no coercion, no typo that silently evaluates to `false`, and no ambiguity:
+
+```js
+const { Verdict } = require('pompelmi');
+
+if (result === Verdict.Clean) { }     // correct — always works
+if (result === Verdict.Malicious) { } // correct
+if (result === Verdict.ScanError) { } // correct
+```
+
+Symbols also cannot be accidentally created by user code. No external input can produce a value that equals `Verdict.Malicious` unless pompelmi itself returned it.
+
+---
+
+## The three verdicts
+
+### `Verdict.Clean`
+
+The file was scanned and no known malware signatures were matched.
+
+- Local mode: `clamscan` exited with code `0`.
+- TCP mode: clamd responded with `stream: OK`.
+
+**What it means:** The file passed the scan. It may still be invalid, corrupt, or undesirable — ClamAV only checks for known malware signatures. Complement with MIME type validation and size limits.
+
+### `Verdict.Malicious`
+
+A known virus or malware signature was matched in the file.
+
+- Local mode: `clamscan` exited with code `1`.
+- TCP mode: clamd responded with `stream: <virus-name> FOUND`.
+
+**What to do:** Reject the file immediately. Delete it or move it to quarantine. Log the event. Do not serve it to any user.
+
+```js
+if (result === Verdict.Malicious) {
+  fs.unlinkSync(filePath);
+  logger.warn({ filePath, event: 'malware_detected' });
+  return res.status(422).json({ error: 'Malicious file rejected.' });
+}
+```
+
+### `Verdict.ScanError`
+
+The scan could not complete.
+
+- Local mode: `clamscan` exited with code `2` — I/O error, permission denied, encrypted archive, corrupted file.
+- TCP mode: clamd sent an unexpected or error response.
+
+**What to do:** Treat the file as untrusted. The safe default is to reject it. Do not serve a file whose safety is unknown.
+
+```js
+if (result === Verdict.ScanError) {
+  fs.unlinkSync(filePath);
+  return res.status(422).json({ error: 'Scan incomplete — file rejected as precaution.' });
+}
+```
+
+When to retry: a `ScanError` is appropriate to retry once if you suspect a transient I/O or network issue. Do not retry indefinitely — if the second scan also returns `ScanError`, reject the file.
+
+---
+
+## Comparing verdicts correctly
+
+Always use `===` strict equality:
+
+```js
+const { scan, Verdict } = require('pompelmi');
+
+const result = await scan('/uploads/file.pdf');
+
+// Correct
+if (result === Verdict.Clean)     { /* safe */ }
+if (result === Verdict.Malicious) { /* reject */ }
+if (result === Verdict.ScanError) { /* reject / retry */ }
+
+// Correct — switch works because Symbols are primitives
+switch (result) {
+  case Verdict.Clean:     return 'safe';
+  case Verdict.Malicious: return 'malicious';
+  case Verdict.ScanError: return 'error';
+}
+```
+
+Do not use `==`, `Object.is`, or any other comparison. `===` is sufficient and correct.
+
+---
+
+## Serialising verdicts
+
+Symbols cannot be JSON-serialised directly — `JSON.stringify(Verdict.Clean)` returns `undefined`. Use `.description` to get the string representation:
+
+```js
+Verdict.Clean.description     // 'Clean'
+Verdict.Malicious.description // 'Malicious'
+Verdict.ScanError.description // 'ScanError'
+```
+
+For logging:
+
+```js
+logger.info({
+  filePath,
+  verdict: result.description,
+});
+```
+
+For HTTP responses:
+
+```js
+return res.json({ verdict: result.description });
+// { "verdict": "Clean" }
+```
+
+For database storage:
+
+```js
+await db.scans.insert({
+  filePath,
+  verdict: result.description,
+  scannedAt: new Date(),
+});
+```
+
+---
+
+## The full decision tree
+
+```js
+const { scan, Verdict } = require('pompelmi');
+const fs = require('fs');
+const path = require('path');
+
+async function handleUpload(filePath) {
+  let result;
+
+  try {
+    result = await scan(path.resolve(filePath));
+  } catch (err) {
+    // Hard error — clamscan missing, file not found, killed process, etc.
+    // The file may or may not still exist. Delete it defensively.
+    try { fs.unlinkSync(filePath); } catch {}
+    throw new Error(`Scan failed: ${err.message}`);
+  }
+
+  if (result === Verdict.Malicious) {
+    fs.unlinkSync(filePath);
+    throw new Error('Malicious file rejected.');
+  }
+
+  if (result === Verdict.ScanError) {
+    fs.unlinkSync(filePath);
+    throw new Error('Scan incomplete — file rejected.');
+  }
+
+  // result === Verdict.Clean
+  return filePath;
+}
+```
+
+---
+
+## Verdict Symbols are unique across instances
+
+Each `Verdict` Symbol is created once when pompelmi loads. As long as you use the same `require('pompelmi')` call (or the same `import`), the reference is the same object. You can safely compare verdicts across modules.
+
+```js
+// module-a.js
+const { Verdict: V1 } = require('pompelmi');
+
+// module-b.js
+const { Verdict: V2 } = require('pompelmi');
+
+V1.Clean === V2.Clean // true — Node.js module cache returns the same object
+```

package/wiki/virus-definitions.md

@@ -0,0 +1,194 @@
+# Virus Definitions
+
+ClamAV's detection quality depends entirely on keeping its virus definition database current. Stale definitions miss recent malware. This page covers how to update definitions, automate updates, and verify the database is fresh.
+
+---
+
+## What the database is
+
+ClamAV uses three main database files:
+
+| File | Purpose |
+|------|---------|
+| `main.cvd` | Main virus database (stable, infrequently updated) |
+| `daily.cvd` or `daily.cld` | Daily incremental updates |
+| `bytecode.cvd` | Bytecode signatures for advanced detection |
+
+On Linux the default path is `/var/lib/clamav/`. On macOS (Homebrew) it is typically `/usr/local/var/lib/clamav/` or `/opt/homebrew/var/lib/clamav/`.
+
+---
+
+## Manual update
+
+Run `freshclam` to download or update the database:
+
+```bash
+# Linux
+sudo freshclam
+
+# macOS (Homebrew)
+freshclam
+
+# With verbose output
+freshclam --verbose
+```
+
+`freshclam` connects to ClamAV's mirror network, checks the current version, and downloads only the delta if an update is available.
+
+---
+
+## Automating updates with cron
+
+Update definitions daily:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add — runs freshclam at 2:30 AM every day
+30 2 * * * /usr/bin/freshclam --quiet 2>&1 | logger -t freshclam
+```
+
+Verify the path to `freshclam`:
+
+```bash
+which freshclam
+# /usr/bin/freshclam  or  /opt/homebrew/bin/freshclam
+```
+
+On Linux with `clamav-daemon`:
+
+```bash
+# freshclam daemon (separate from clamd) — manages updates automatically
+sudo systemctl enable clamav-freshclam
+sudo systemctl start clamav-freshclam
+```
+
+---
+
+## Verifying the database is current
+
+```bash
+# Check version and signature date
+clamscan --version
+# ClamAV 1.3.0/27330/Sun Apr 28 06:25:00 2024
+
+# freshclam shows what is installed vs available
+freshclam --verbose
+```
+
+The number after the slash (e.g. `27330`) is the database version. Compare it to the ClamAV website to see if you are up to date.
+
+---
+
+## Docker: automatic updates
+
+The official `clamav/clamav:stable` image runs `freshclam` on startup and periodically in the background. No extra configuration is needed.
+
+To verify inside the running container:
+
+```bash
+docker compose exec clamav freshclam --verbose
+```
+
+To force an immediate update:
+
+```bash
+docker compose exec clamav freshclam
+```
+
+---
+
+## Docker: persisting the database across restarts
+
+Without a named volume, Docker re-downloads the full database (~300 MB) every time the container restarts. Use a named volume:
+
+```yaml
+services:
+  clamav:
+    image: clamav/clamav:stable
+    volumes:
+      - clamav_db:/var/lib/clamav
+
+volumes:
+  clamav_db:
+```
+
+With the volume in place, only incremental updates are downloaded after the first start. Restart time drops from 2–3 minutes to a few seconds.
+
+---
+
+## Programmatic update with pompelmi
+
+pompelmi exports an internal `updateClamAVDatabase()` utility:
+
+```js
+const { updateClamAVDatabase } = require('./node_modules/pompelmi/src/ClamAVDatabaseUpdater');
+
+await updateClamAVDatabase();
+// Resolves: 'Database already up to date.' or 'Database updated successfully.'
+```
+
+This is intended for initial setup scripts, not ongoing updates. Prefer cron or the clamd-freshclam service for production.
+
+---
+
+## What happens when definitions are stale
+
+If the database is very old (months or years out of date):
+
+- Recent malware samples will not be detected — ClamAV will return `Verdict.Clean` for files that are actually malicious.
+- `clamscan` may print warnings about outdated definitions to stderr.
+- The clamd daemon may refuse to start if the database is too old (configurable via `DatabaseAge` in `clamd.conf`).
+
+pompelmi itself does not check definition age — it calls ClamAV and maps the result. The responsibility for keeping definitions current is yours.
+
+---
+
+## Alerting on stale definitions
+
+Parse the `clamscan --version` output to check the database date and alert if it is too old:
+
+```js
+const { execSync } = require('child_process');
+
+function getDatabaseAge() {
+  const output = execSync('clamscan --version').toString();
+  // e.g. "ClamAV 1.3.0/27330/Sun Apr 28 06:25:00 2024"
+  const match = output.match(/\/(\d+)\//);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+const version = getDatabaseAge();
+const MINIMUM_VERSION = 27000; // update this periodically
+
+if (version && version < MINIMUM_VERSION) {
+  console.warn(`ClamAV database version ${version} is below minimum ${MINIMUM_VERSION}. Run freshclam.`);
+}
+```
+
+Or check by date from `freshclam` logs:
+
+```bash
+grep 'up to date' /var/log/clamav/freshclam.log | tail -1
+```
+
+---
+
+## Rate limits on ClamAV mirrors
+
+ClamAV's public mirror network rate-limits `freshclam` requests. Do not run `freshclam` more than 4 times per hour — the mirrors will temporarily block your IP. The default `freshclam` cron interval of once per day is appropriate for most deployments.
+
+For organisations with many servers, set up a local ClamAV mirror or use a private update proxy.
+
+---
+
+## Platform database paths
+
+| Platform | Default database path |
+|----------|----------------------|
+| Linux (Debian/Ubuntu) | `/var/lib/clamav/` |
+| macOS (Homebrew x86) | `/usr/local/var/lib/clamav/` |
+| macOS (Homebrew Apple Silicon) | `/opt/homebrew/var/lib/clamav/` |
+| Windows | `C:\ProgramData\ClamAV\` |
+| Docker (`clamav/clamav`) | `/var/lib/clamav/` |