pompelmi 1.4.0 → 1.6.0

package/wiki/error-handling.md

@@ -0,0 +1,242 @@
+# Error Handling
+
+pompelmi has two distinct failure modes that require different handling: **rejected Promises** (the function threw) and **`Verdict.ScanError`** (the scan completed but could not determine safety). Understanding the difference is critical to building a secure upload pipeline.
+
+---
+
+## The two failure modes
+
+### 1. Rejected Promise (the scan function threw)
+
+`scan()`, `scanBuffer()`, `scanStream()`, and `scanDirectory()` reject when something prevents the scan from running at all — not when the scan completes and finds a problem.
+
+Common rejection causes:
+
+| Error message | Cause |
+|---------------|-------|
+| `filePath must be a string` | Wrong argument type |
+| `File not found: <path>` | File does not exist |
+| `ENOENT` | `clamscan` not installed or not in PATH |
+| `Unexpected exit code: N` | ClamAV internal error |
+| `Process killed by signal: SIGTERM` | Process killed (OOM, timeout) |
+| `clamd connection timed out after Nms` | TCP timeout exceeded |
+| `buffer must be a Buffer` | Wrong argument to `scanBuffer()` |
+| `stream must be a Readable` | Wrong argument to `scanStream()` |
+| `dirPath must be a string` | Wrong argument to `scanDirectory()` |
+| `Directory not found: <path>` | Directory does not exist |
+
+These are programming errors or infrastructure failures. Handle them with `try/catch`.
+
+### 2. `Verdict.ScanError` (scan completed, result unknown)
+
+`Verdict.ScanError` resolves (does not throw) and indicates ClamAV ran but could not produce a clean/malicious verdict. Common causes: encrypted archives, corrupt files, permission errors, I/O issues.
+
+---
+
+## The secure default: reject on both
+
+The safest policy: any outcome other than `Verdict.Clean` results in rejection.
+
+```js
+const { scan, Verdict } = require('pompelmi');
+const fs = require('fs');
+
+async function scanAndAccept(filePath) {
+  try {
+    const result = await scan(filePath, { host: 'clamav', port: 3310 });
+
+    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 as precaution.');
+    }
+
+    return filePath; // Verdict.Clean
+  } catch (err) {
+    // Covers both scan() rejections and our own thrown Errors above.
+    // Delete the file defensively if it still exists.
+    try { fs.unlinkSync(filePath); } catch {}
+    throw err;
+  }
+}
+```
+
+---
+
+## When to retry `ScanError`
+
+A `ScanError` caused by a transient network blip or a momentary clamd overload is worth one retry. A `ScanError` caused by a corrupt file or encrypted archive will always return `ScanError` — retrying wastes time.
+
+```js
+async function scanWithRetry(filePath, opts, retries = 1) {
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const result = await scan(filePath, opts);
+      if (result !== Verdict.ScanError || attempt === retries) {
+        return result;
+      }
+      // ScanError on non-final attempt — wait briefly and retry
+      await new Promise(r => setTimeout(r, 500));
+    } catch (err) {
+      if (attempt === retries) throw err;
+    }
+  }
+}
+```
+
+Do not retry `Verdict.Malicious` — the signature match is deterministic.
+
+---
+
+## Cleanup with `finally`
+
+Ensure temp files are always deleted regardless of scan outcome:
+
+```js
+const os   = require('os');
+const fs   = require('fs');
+const path = require('path');
+const { scan, Verdict } = require('pompelmi');
+
+async function scanBuffer_manual(buffer) {
+  const tmpPath = path.join(os.tmpdir(), `scan-${Date.now()}.tmp`);
+  fs.writeFileSync(tmpPath, buffer);
+
+  try {
+    return await scan(tmpPath);
+  } finally {
+    try { fs.unlinkSync(tmpPath); } catch {}
+  }
+}
+```
+
+`scanBuffer()` handles this `finally` pattern internally in local mode — you don't need to replicate it when using the API directly.
+
+---
+
+## Express error handling pattern
+
+```js
+const express = require('express');
+const multer  = require('multer');
+const fs      = require('fs');
+const { scan, Verdict } = require('pompelmi');
+
+const app    = express();
+const upload = multer({ dest: './uploads', limits: { fileSize: 10 * 1024 * 1024 } });
+
+app.post('/upload', upload.single('file'), async (req, res, next) => {
+  if (!req.file) return res.status(400).json({ error: 'No file uploaded.' });
+
+  try {
+    const result = await scan(req.file.path, { host: 'clamav', port: 3310 });
+
+    if (result === Verdict.Malicious) {
+      fs.unlinkSync(req.file.path);
+      return res.status(422).json({ error: 'Malicious file rejected.' });
+    }
+
+    if (result === Verdict.ScanError) {
+      fs.unlinkSync(req.file.path);
+      return res.status(422).json({ error: 'Scan failed — file rejected.' });
+    }
+
+    return res.json({ ok: true, filename: req.file.filename });
+  } catch (err) {
+    try { fs.unlinkSync(req.file.path); } catch {}
+    next(err); // forward to Express error middleware
+  }
+});
+
+// Global error handler
+app.use((err, req, res, next) => {
+  console.error(err);
+  res.status(500).json({ error: 'Internal scan error.' });
+});
+```
+
+---
+
+## Logging best practices
+
+Log rejections with enough context to investigate later — but never log file contents.
+
+```js
+const logger = require('./logger'); // pino, winston, etc.
+
+if (result === Verdict.Malicious) {
+  logger.warn({
+    event:       'malware_detected',
+    filePath,
+    originalname: req.file.originalname,
+    mimetype:     req.file.mimetype,
+    size:         req.file.size,
+    userId:       req.user?.id,
+    ip:           req.ip,
+  });
+}
+```
+
+For `ScanError`:
+
+```js
+if (result === Verdict.ScanError) {
+  logger.warn({
+    event:    'scan_error',
+    filePath,
+    mimetype: req.file.mimetype,
+    size:     req.file.size,
+  });
+}
+```
+
+For scan function rejections:
+
+```js
+} catch (err) {
+  logger.error({
+    event:   'scan_threw',
+    message: err.message,
+    filePath,
+  });
+}
+```
+
+---
+
+## HTTP status code conventions
+
+| Situation | Recommended status |
+|-----------|-------------------|
+| No file in request | `400 Bad Request` |
+| Wrong argument (programming error) | `400 Bad Request` |
+| `Verdict.Malicious` | `422 Unprocessable Entity` |
+| `Verdict.ScanError` (reject policy) | `422 Unprocessable Entity` |
+| `scan()` throws (infra error) | `500 Internal Server Error` |
+| File too large (pre-scan) | `413 Content Too Large` |
+| `Verdict.Clean` | `200 OK` / `201 Created` |
+
+---
+
+## `scanDirectory()` error handling
+
+Per-file failures in `scanDirectory()` go into the `errors` array — the function itself only rejects on argument errors or missing directory.
+
+```js
+const { scanDirectory } = require('pompelmi');
+
+try {
+  const results = await scanDirectory('/uploads');
+  if (results.errors.length > 0) {
+    logger.warn({ event: 'scan_errors', paths: results.errors });
+    // Decide: reject the whole batch, or only reject the errored files
+  }
+} catch (err) {
+  // dirPath not a string, or directory not found
+  logger.error({ event: 'scan_threw', message: err.message });
+}
+```

package/wiki/express-integration.md

@@ -0,0 +1,227 @@
+# Express Integration
+
+This page covers integrating pompelmi into an Express application for file upload scanning — both disk storage (scan by path) and memory storage (scan by buffer).
+
+---
+
+## Setup
+
+```bash
+npm install pompelmi multer express
+```
+
+---
+
+## Disk storage (scan by file path)
+
+multer writes the uploaded file to disk before your route handler runs. Call `scan(req.file.path)` to scan it.
+
+```js
+const express = require('express');
+const multer  = require('multer');
+const fs      = require('fs');
+const path    = require('path');
+const { scan, Verdict } = require('pompelmi');
+
+const upload = multer({ dest: path.join(__dirname, 'uploads') });
+const app    = express();
+
+app.post('/upload', upload.single('file'), async (req, res) => {
+  if (!req.file) {
+    return res.status(400).json({ error: 'No file uploaded.' });
+  }
+
+  const filePath = req.file.path;
+
+  try {
+    const result = await scan(filePath);
+
+    if (result === Verdict.Malicious) {
+      fs.unlinkSync(filePath);
+      return res.status(422).json({ error: 'Malicious file rejected.' });
+    }
+
+    if (result === Verdict.ScanError) {
+      fs.unlinkSync(filePath);
+      return res.status(422).json({ error: 'Scan incomplete — file rejected as precaution.' });
+    }
+
+    // Verdict.Clean — rename to final destination or store as-is
+    return res.json({ ok: true, filename: req.file.filename });
+  } catch (err) {
+    // clamscan not in PATH, file not found, process killed, etc.
+    try { fs.unlinkSync(filePath); } catch {}
+    return res.status(500).json({ error: `Scan failed: ${err.message}` });
+  }
+});
+
+app.listen(3000);
+```
+
+### With TCP mode (Docker sidecar)
+
+```js
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST || '127.0.0.1',
+  port: Number(process.env.CLAMAV_PORT) || 3310,
+  timeout: 30_000,
+};
+
+const result = await scan(filePath, SCAN_OPTS);
+```
+
+---
+
+## Memory storage (scan by buffer)
+
+When you use `multer({ storage: multer.memoryStorage() })`, the file is never written to disk — it lives in `req.file.buffer`. Use `scanBuffer()` instead of `scan()`.
+
+```js
+const express = require('express');
+const multer  = require('multer');
+const { scanBuffer, Verdict } = require('pompelmi');
+
+const upload = multer({ storage: multer.memoryStorage() });
+const app    = express();
+
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST,
+  port: 3310,
+};
+
+app.post('/upload', upload.single('file'), async (req, res) => {
+  if (!req.file) {
+    return res.status(400).json({ error: 'No file uploaded.' });
+  }
+
+  try {
+    const result = await scanBuffer(req.file.buffer, SCAN_OPTS);
+
+    if (result === Verdict.Malicious) {
+      return res.status(422).json({ error: 'Malicious file rejected.' });
+    }
+
+    if (result === Verdict.ScanError) {
+      return res.status(422).json({ error: 'Scan incomplete — file rejected.' });
+    }
+
+    // Clean — forward buffer to storage (S3, database, disk)
+    return res.json({ ok: true, originalname: req.file.originalname });
+  } catch (err) {
+    return res.status(500).json({ error: `Scan failed: ${err.message}` });
+  }
+});
+
+app.listen(3000);
+```
+
+---
+
+## Scanning multiple files in one request
+
+```js
+app.post('/upload-many', upload.array('files', 10), async (req, res) => {
+  if (!req.files || req.files.length === 0) {
+    return res.status(400).json({ error: 'No files uploaded.' });
+  }
+
+  const results = await Promise.allSettled(
+    req.files.map(async (file) => {
+      const verdict = await scan(file.path, SCAN_OPTS);
+      return { file, verdict };
+    })
+  );
+
+  const rejected = [];
+  const accepted = [];
+
+  for (const r of results) {
+    if (r.status === 'rejected') {
+      rejected.push({ filename: '?', reason: r.reason.message });
+      continue;
+    }
+    const { file, verdict } = r.value;
+    if (verdict !== Verdict.Clean) {
+      try { fs.unlinkSync(file.path); } catch {}
+      rejected.push({ filename: file.originalname, reason: verdict.description });
+    } else {
+      accepted.push(file.originalname);
+    }
+  }
+
+  if (rejected.length > 0) {
+    return res.status(422).json({ accepted, rejected });
+  }
+  return res.json({ ok: true, accepted });
+});
+```
+
+---
+
+## Centralised error handling middleware
+
+Extract scan logic into middleware for reuse across routes:
+
+```js
+async function scanUpload(req, res, next) {
+  if (!req.file) return next();
+
+  const filePath = req.file.path;
+
+  try {
+    const result = await scan(filePath, SCAN_OPTS);
+
+    if (result !== Verdict.Clean) {
+      try { fs.unlinkSync(filePath); } catch {}
+      const status = result === Verdict.Malicious ? 422 : 422;
+      return res.status(status).json({ error: `Upload rejected: ${result.description}` });
+    }
+
+    next();
+  } catch (err) {
+    try { fs.unlinkSync(filePath); } catch {}
+    next(err);
+  }
+}
+
+// Use it
+app.post('/profile-photo', upload.single('photo'), scanUpload, (req, res) => {
+  res.json({ ok: true, path: req.file.path });
+});
+```
+
+---
+
+## HTTP status codes
+
+| Situation | Status |
+|-----------|--------|
+| No file in request | `400 Bad Request` |
+| `Verdict.Malicious` | `422 Unprocessable Entity` |
+| `Verdict.ScanError` | `422 Unprocessable Entity` |
+| `scan()` throws | `500 Internal Server Error` |
+| `Verdict.Clean` | `200 OK` (or `201 Created` after storing) |
+
+---
+
+## File size limits
+
+Always set a file size limit on multer to prevent large uploads from exhausting memory or disk:
+
+```js
+const upload = multer({
+  dest: './uploads',
+  limits: { fileSize: 10 * 1024 * 1024 }, // 10 MB
+});
+```
+
+multer returns a `MulterError` (subclass of `Error`) when the limit is exceeded. Handle it in your error middleware:
+
+```js
+app.use((err, req, res, next) => {
+  if (err.code === 'LIMIT_FILE_SIZE') {
+    return res.status(413).json({ error: 'File too large.' });
+  }
+  next(err);
+});
+```

package/wiki/fastify-integration.md

@@ -0,0 +1,207 @@
+# Fastify Integration
+
+Complete guide to integrating pompelmi into a Fastify application. Covers disk-based scanning, stream-based scanning with `scanStream()`, and error handling.
+
+---
+
+## Setup
+
+```bash
+npm install pompelmi fastify @fastify/multipart
+```
+
+---
+
+## Disk-based scanning (save to disk first, then scan)
+
+This pattern saves the uploaded file to disk via `pipeline`, then scans it by path. Most straightforward for large files.
+
+```js
+const Fastify   = require('fastify');
+const { pipeline } = require('stream/promises');
+const fs        = require('fs');
+const path      = require('path');
+const { scan, Verdict } = require('pompelmi');
+
+const app = Fastify({ logger: true });
+app.register(require('@fastify/multipart'));
+
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST,
+  port: Number(process.env.CLAMAV_PORT) || 3310,
+  timeout: 30_000,
+};
+
+app.post('/upload', async (req, reply) => {
+  const data     = await req.file();
+  const filePath = path.join('./uploads', `${Date.now()}-${data.filename}`);
+
+  // Write to disk
+  await pipeline(data.file, fs.createWriteStream(filePath));
+
+  let result;
+  try {
+    result = await scan(filePath, SCAN_OPTS);
+  } catch (err) {
+    try { fs.unlinkSync(filePath); } catch {}
+    return reply.code(500).send({ error: `Scan failed: ${err.message}` });
+  }
+
+  if (result !== Verdict.Clean) {
+    try { fs.unlinkSync(filePath); } catch {}
+    return reply.code(422).send({ error: `Upload rejected: ${result.description}` });
+  }
+
+  return reply.send({ ok: true, filename: path.basename(filePath) });
+});
+
+app.listen({ port: 3000 });
+```
+
+---
+
+## Stream-based scanning (no disk I/O in TCP mode)
+
+When using TCP mode (clamd sidecar), pass the upload stream directly to `scanStream()`. The file never touches the application host's disk.
+
+```js
+const Fastify = require('fastify');
+const { scanStream, Verdict } = require('pompelmi');
+
+const app = Fastify({ logger: true });
+app.register(require('@fastify/multipart'));
+
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST || 'clamav',
+  port: 3310,
+  timeout: 30_000,
+};
+
+app.post('/upload', async (req, reply) => {
+  const data = await req.file();
+
+  let result;
+  try {
+    result = await scanStream(data.file, SCAN_OPTS);
+  } catch (err) {
+    return reply.code(500).send({ error: `Scan failed: ${err.message}` });
+  }
+
+  if (result === Verdict.Malicious) {
+    return reply.code(422).send({ error: 'Malicious file rejected.' });
+  }
+
+  if (result === Verdict.ScanError) {
+    return reply.code(422).send({ error: 'Scan incomplete — file rejected.' });
+  }
+
+  // Stream is consumed — if you need to store the file you must re-read it.
+  // With stream scanning, save to storage (S3, disk) in a separate step
+  // using the original source, not data.file (already consumed).
+  return reply.send({ ok: true, filename: data.filename });
+});
+
+app.listen({ port: 3000 });
+```
+
+> **Note on stream consumption:** Once `scanStream()` consumes `data.file`, the stream is exhausted. If you need to store the file after scanning, either save it to disk first (disk-based pattern) or scan and upload to S3 in parallel using a passthrough stream.
+
+---
+
+## Scanning multiple files
+
+```js
+app.post('/upload-many', async (req, reply) => {
+  const parts   = req.files();
+  const results = [];
+
+  for await (const part of parts) {
+    const filePath = path.join('./uploads', `${Date.now()}-${part.filename}`);
+    await pipeline(part.file, fs.createWriteStream(filePath));
+
+    const verdict = await scan(filePath, SCAN_OPTS).catch(err => {
+      try { fs.unlinkSync(filePath); } catch {}
+      return null;
+    });
+
+    if (!verdict || verdict !== Verdict.Clean) {
+      try { fs.unlinkSync(filePath); } catch {}
+      results.push({ filename: part.filename, accepted: false, reason: verdict?.description ?? 'scan_error' });
+    } else {
+      results.push({ filename: part.filename, accepted: true });
+    }
+  }
+
+  const anyRejected = results.some(r => !r.accepted);
+  return reply.code(anyRejected ? 422 : 200).send({ results });
+});
+```
+
+---
+
+## Error handling with `setErrorHandler`
+
+Register a global error handler for unexpected failures:
+
+```js
+app.setErrorHandler((err, req, reply) => {
+  req.log.error(err);
+  reply.code(500).send({ error: 'Internal server error.' });
+});
+```
+
+For multer-equivalent size limits with `@fastify/multipart`:
+
+```js
+app.register(require('@fastify/multipart'), {
+  limits: {
+    fileSize: 10 * 1024 * 1024, // 10 MB
+  },
+});
+
+app.setErrorHandler((err, req, reply) => {
+  if (err.code === 'FST_REQ_FILE_TOO_LARGE') {
+    return reply.code(413).send({ error: 'File too large.' });
+  }
+  reply.code(500).send({ error: err.message });
+});
+```
+
+---
+
+## HTTP status codes
+
+| Situation | Status |
+|-----------|--------|
+| No file part in request | `400 Bad Request` |
+| `Verdict.Malicious` | `422 Unprocessable Entity` |
+| `Verdict.ScanError` | `422 Unprocessable Entity` |
+| `scan()` / `scanStream()` throws | `500 Internal Server Error` |
+| File too large | `413 Content Too Large` |
+| `Verdict.Clean` | `200 OK` |
+
+---
+
+## TypeScript
+
+```ts
+import Fastify from 'fastify';
+import multipart from '@fastify/multipart';
+import { scanStream, Verdict } from 'pompelmi';
+
+const app = Fastify();
+app.register(multipart);
+
+app.post('/upload', async (req, reply) => {
+  const data = await req.file();
+  if (!data) return reply.code(400).send({ error: 'No file.' });
+
+  const result = await scanStream(data.file, { host: 'clamav', port: 3310 });
+
+  if (result !== Verdict.Clean) {
+    return reply.code(422).send({ error: result.description });
+  }
+
+  return reply.send({ ok: true });
+});
+```