pompelmi 1.5.0 → 1.7.0

package/wiki/multer-memory-storage.md

@@ -0,0 +1,166 @@
+# multer Memory Storage
+
+When you use `multer({ storage: multer.memoryStorage() })`, the uploaded file is never written to disk. It lives entirely in `req.file.buffer` as a Node.js `Buffer`. This page explains why `scan()` does not work in this case and how `scanBuffer()` solves it.
+
+---
+
+## Why `scan()` doesn't work with memoryStorage
+
+`scan()` requires a file path — it calls `clamscan <filePath>` or streams the file at that path to clamd. With `memoryStorage`, there is no path:
+
+```js
+const upload = multer({ storage: multer.memoryStorage() });
+
+app.post('/upload', upload.single('file'), async (req, res) => {
+  console.log(req.file.path);   // undefined — no file on disk
+  console.log(req.file.buffer); // <Buffer 25 50 44 ...> — file is here
+
+  // This throws "filePath must be a string"
+  await scan(req.file.path);
+});
+```
+
+---
+
+## Use `scanBuffer()` instead
+
+```js
+const express = require('express');
+const multer  = require('multer');
+const { scanBuffer, Verdict } = require('pompelmi');
+
+const app    = express();
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits:  { fileSize: 10 * 1024 * 1024 }, // 10 MB
+});
+
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST,
+  port: Number(process.env.CLAMAV_PORT) || 3310,
+  timeout: 30_000,
+};
+
+app.post('/upload', upload.single('file'), async (req, res) => {
+  if (!req.file) {
+    return res.status(400).json({ error: 'No file uploaded.' });
+  }
+
+  let result;
+  try {
+    result = await scanBuffer(req.file.buffer, SCAN_OPTS);
+  } catch (err) {
+    return res.status(500).json({ error: `Scan failed: ${err.message}` });
+  }
+
+  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.' });
+  }
+
+  // Verdict.Clean — buffer is available for forwarding to S3, DB, etc.
+  return res.json({ ok: true, size: req.file.size });
+});
+
+app.listen(3000);
+```
+
+---
+
+## How `scanBuffer()` works in each mode
+
+| Mode | Behaviour |
+|------|-----------|
+| **TCP** (`host` set) | Buffer is streamed directly to clamd via INSTREAM — zero disk I/O on the application host. |
+| **Local** (no `host`) | Buffer is written to a temp file in `os.tmpdir()`, scanned with `clamscan`, then deleted in a `finally` block. |
+
+For `memoryStorage` workloads, TCP mode is strongly recommended: the whole point of keeping the file in memory is to avoid touching disk, and TCP mode preserves that guarantee.
+
+---
+
+## Multiple files with `upload.array()`
+
+```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 scanResults = await Promise.allSettled(
+    req.files.map(async (file) => {
+      const verdict = await scanBuffer(file.buffer, SCAN_OPTS);
+      return { originalname: file.originalname, verdict };
+    })
+  );
+
+  const accepted = [];
+  const rejected = [];
+
+  for (const r of scanResults) {
+    if (r.status === 'rejected') {
+      rejected.push({ originalname: '?', reason: 'scan_failed' });
+      continue;
+    }
+    const { originalname, verdict } = r.value;
+    if (verdict === Verdict.Clean) {
+      accepted.push(originalname);
+    } else {
+      rejected.push({ originalname, reason: verdict.description });
+    }
+  }
+
+  if (rejected.length > 0) {
+    return res.status(422).json({ accepted, rejected });
+  }
+  return res.json({ ok: true, accepted });
+});
+```
+
+---
+
+## Memory usage considerations
+
+With `memoryStorage`, every uploaded file occupies memory for the duration of the request. For large files or high concurrency, this can exhaust the Node.js heap. Options:
+
+1. **Set a file size limit** — always set `limits.fileSize` on multer.
+2. **Use disk storage for large files** — fall back to `diskStorage` for files above a threshold.
+3. **Use `scanStream()` instead** — pipe the multipart stream directly to `scanStream()` without buffering the entire file. This requires bypassing multer and parsing multipart manually (e.g. with `busboy`).
+
+```js
+// scanStream with busboy — no full buffering
+const busboy = require('busboy');
+
+app.post('/upload-stream', (req, res) => {
+  const bb = busboy({ headers: req.headers });
+
+  bb.on('file', async (_name, fileStream, _info) => {
+    const result = await scanStream(fileStream, SCAN_OPTS);
+
+    if (result !== Verdict.Clean) {
+      return res.status(422).json({ error: result.description });
+    }
+    return res.json({ ok: true });
+  });
+
+  req.pipe(bb);
+});
+```
+
+---
+
+## After scanning: forward to S3
+
+```js
+const { PutObjectCommand } = require('@aws-sdk/client-s3');
+
+// After confirmed Verdict.Clean
+await s3.send(new PutObjectCommand({
+  Bucket:      process.env.S3_BUCKET,
+  Key:         `uploads/${Date.now()}-${req.file.originalname}`,
+  Body:        req.file.buffer,
+  ContentType: req.file.mimetype,
+}));
+```

package/wiki/nestjs-integration.md

@@ -0,0 +1,228 @@
+# NestJS Integration
+
+Integrate pompelmi into a NestJS application using a custom `PipeTransform` or `Interceptor` to scan uploaded files before they reach your controller.
+
+---
+
+## Setup
+
+```bash
+npm install pompelmi @nestjs/platform-express multer
+npm install -D @types/multer
+```
+
+---
+
+## Custom pipe: `FileScanPipe`
+
+A `PipeTransform` that receives the `Express.Multer.File` object from `FileInterceptor` and rejects it if ClamAV detects malware. Throw `BadRequestException` or `UnprocessableEntityException` as appropriate.
+
+```ts
+// file-scan.pipe.ts
+import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
+import { scan, Verdict } from 'pompelmi';
+
+@Injectable()
+export class FileScanPipe implements PipeTransform {
+  private readonly opts = {
+    host: process.env.CLAMAV_HOST,
+    port: Number(process.env.CLAMAV_PORT) || 3310,
+    timeout: 30_000,
+  };
+
+  async transform(file: Express.Multer.File): Promise<Express.Multer.File> {
+    if (!file) throw new BadRequestException('No file uploaded.');
+
+    let result: symbol;
+    try {
+      result = await scan(file.path, this.opts);
+    } catch (err) {
+      throw new BadRequestException(`Scan failed: ${(err as Error).message}`);
+    }
+
+    if (result === Verdict.Malicious) {
+      throw new BadRequestException('Malicious file rejected.');
+    }
+
+    if (result === Verdict.ScanError) {
+      throw new BadRequestException('Scan incomplete — file rejected.');
+    }
+
+    return file;
+  }
+}
+```
+
+---
+
+## Using the pipe in a controller
+
+```ts
+// upload.controller.ts
+import {
+  Controller,
+  Post,
+  UploadedFile,
+  UseInterceptors,
+} from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { FileScanPipe } from './file-scan.pipe';
+import * as diskStorage from 'multer';
+
+@Controller('upload')
+export class UploadController {
+  @Post()
+  @UseInterceptors(
+    FileInterceptor('file', {
+      dest: './uploads',
+      limits: { fileSize: 10 * 1024 * 1024 },
+    }),
+  )
+  async uploadFile(
+    @UploadedFile(FileScanPipe) file: Express.Multer.File,
+  ) {
+    return { ok: true, filename: file.filename };
+  }
+}
+```
+
+`FileInterceptor` writes the file to `dest` before the pipe runs, so `file.path` is available.
+
+---
+
+## Memory storage with `scanBuffer()`
+
+If you use `multer.memoryStorage()` the file is in `file.buffer`. Update the pipe:
+
+```ts
+// file-scan-buffer.pipe.ts
+import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
+import { scanBuffer, Verdict } from 'pompelmi';
+
+@Injectable()
+export class FileScanBufferPipe implements PipeTransform {
+  private readonly opts = {
+    host: process.env.CLAMAV_HOST,
+    port: Number(process.env.CLAMAV_PORT) || 3310,
+  };
+
+  async transform(file: Express.Multer.File): Promise<Express.Multer.File> {
+    if (!file) throw new BadRequestException('No file uploaded.');
+
+    const result = await scanBuffer(file.buffer, this.opts).catch((err) => {
+      throw new BadRequestException(`Scan failed: ${err.message}`);
+    });
+
+    if (result !== Verdict.Clean) {
+      throw new BadRequestException(`Upload rejected: ${result.description}`);
+    }
+
+    return file;
+  }
+}
+```
+
+Controller stays the same; swap `FileScanPipe` for `FileScanBufferPipe`:
+
+```ts
+@UseInterceptors(
+  FileInterceptor('file', {
+    storage: multer.memoryStorage(),
+    limits: { fileSize: 10 * 1024 * 1024 },
+  }),
+)
+async uploadFile(@UploadedFile(FileScanBufferPipe) file: Express.Multer.File) {
+  // file.buffer is the scanned content
+  return { ok: true, size: file.size };
+}
+```
+
+---
+
+## Module setup
+
+Register the pipe as a provider if you want it injectable via DI:
+
+```ts
+// upload.module.ts
+import { Module } from '@nestjs/common';
+import { UploadController } from './upload.controller';
+import { FileScanPipe } from './file-scan.pipe';
+
+@Module({
+  controllers: [UploadController],
+  providers: [FileScanPipe],
+})
+export class UploadModule {}
+```
+
+Or use it directly inline without DI — the `new FileScanPipe()` form works equally well:
+
+```ts
+@UploadedFile(new FileScanPipe())
+```
+
+---
+
+## Interceptor approach
+
+An `NestInterceptor` runs around the entire handler. Use this if you want to clean up the file after the handler completes regardless of outcome.
+
+```ts
+// scan.interceptor.ts
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  BadRequestException,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { scan, Verdict } from 'pompelmi';
+
+@Injectable()
+export class ScanInterceptor implements NestInterceptor {
+  async intercept(ctx: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
+    const req = ctx.switchToHttp().getRequest();
+    const file: Express.Multer.File | undefined = req.file;
+
+    if (!file) return next.handle();
+
+    const result = await scan(file.path, {
+      host: process.env.CLAMAV_HOST,
+      port: 3310,
+    });
+
+    if (result !== Verdict.Clean) {
+      throw new BadRequestException(`Upload rejected: ${result.description}`);
+    }
+
+    return next.handle();
+  }
+}
+```
+
+Apply it at the controller or handler level:
+
+```ts
+@UseInterceptors(FileInterceptor('file', { dest: './uploads' }), ScanInterceptor)
+@Post()
+async uploadFile(@UploadedFile() file: Express.Multer.File) {
+  return { ok: true, filename: file.filename };
+}
+```
+
+---
+
+## Cleanup on rejection
+
+When the file is rejected, delete it to avoid accumulating rejected uploads on disk:
+
+```ts
+import * as fs from 'fs';
+
+if (result !== Verdict.Clean) {
+  try { fs.unlinkSync(file.path); } catch {}
+  throw new BadRequestException('Malicious file rejected.');
+}
+```

package/wiki/nextjs-integration.md

@@ -0,0 +1,209 @@
+# Next.js Integration
+
+Scan uploaded files in Next.js API routes before writing them to disk or forwarding them to S3. Covers both the App Router (Next.js 13+) and the Pages Router.
+
+---
+
+## App Router (Next.js 13+)
+
+### Scan from `formData()` — scan buffer, upload to S3 if clean
+
+In the App Router, request bodies are parsed via the Web Fetch API. Use `request.formData()` to get the file as a `Blob`, convert it to a Node.js `Buffer`, then call `scanBuffer()`.
+
+```ts
+// app/api/upload/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { scanBuffer, Verdict } from 'pompelmi';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST,
+  port: Number(process.env.CLAMAV_PORT) || 3310,
+  timeout: 30_000,
+};
+
+export async function POST(request: NextRequest) {
+  const form = await request.formData();
+  const file = form.get('file');
+
+  if (!(file instanceof File)) {
+    return NextResponse.json({ error: 'No file uploaded.' }, { status: 400 });
+  }
+
+  const arrayBuffer = await file.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+
+  let result: symbol;
+  try {
+    result = await scanBuffer(buffer, SCAN_OPTS);
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Scan failed: ${(err as Error).message}` },
+      { status: 500 }
+    );
+  }
+
+  if (result === Verdict.Malicious) {
+    return NextResponse.json({ error: 'Malicious file rejected.' }, { status: 422 });
+  }
+
+  if (result === Verdict.ScanError) {
+    return NextResponse.json(
+      { error: 'Scan incomplete — file rejected as precaution.' },
+      { status: 422 }
+    );
+  }
+
+  // Upload to S3 only after a clean scan
+  await s3.send(new PutObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key:    `uploads/${Date.now()}-${file.name}`,
+    Body:   buffer,
+    ContentType: file.type,
+  }));
+
+  return NextResponse.json({ ok: true });
+}
+```
+
+### Disable Next.js body parsing
+
+By default, Next.js App Router does not parse multipart bodies — the `request.formData()` call handles it natively. No special config needed.
+
+---
+
+## Pages Router
+
+### With `formidable` — scan by file path
+
+The Pages Router does not handle multipart natively. Use `formidable` to parse the upload, then scan the temp file path.
+
+```bash
+npm install pompelmi formidable
+npm install -D @types/formidable
+```
+
+```ts
+// pages/api/upload.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import formidable, { File as FormidableFile } from 'formidable';
+import fs from 'fs';
+import { scan, Verdict } from 'pompelmi';
+
+export const config = {
+  api: { bodyParser: false }, // required for multipart
+};
+
+const SCAN_OPTS = {
+  host: process.env.CLAMAV_HOST,
+  port: Number(process.env.CLAMAV_PORT) || 3310,
+};
+
+function parseForm(req: NextApiRequest): Promise<{ file: FormidableFile }> {
+  return new Promise((resolve, reject) => {
+    const form = formidable({ uploadDir: '/tmp', keepExtensions: true });
+    form.parse(req, (err, _fields, files) => {
+      if (err) return reject(err);
+      const file = Array.isArray(files.file) ? files.file[0] : files.file;
+      if (!file) return reject(new Error('No file.'));
+      resolve({ file });
+    });
+  });
+}
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'POST') return res.status(405).end();
+
+  let file: FormidableFile;
+  try {
+    ({ file } = await parseForm(req));
+  } catch (err) {
+    return res.status(400).json({ error: 'Upload failed.' });
+  }
+
+  const filePath = file.filepath;
+
+  try {
+    const result = await scan(filePath, SCAN_OPTS);
+
+    if (result !== Verdict.Clean) {
+      fs.unlinkSync(filePath);
+      return res.status(422).json({ error: `Upload rejected: ${result.description}` });
+    }
+
+    // Move or store the clean file
+    return res.status(200).json({ ok: true });
+  } catch (err) {
+    try { fs.unlinkSync(filePath); } catch {}
+    return res.status(500).json({ error: `Scan failed: ${(err as Error).message}` });
+  }
+}
+```
+
+---
+
+## Client-side upload
+
+```tsx
+// components/UploadForm.tsx
+'use client';
+import { useState } from 'react';
+
+export default function UploadForm() {
+  const [status, setStatus] = useState('');
+
+  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    const form = e.currentTarget;
+    const data = new FormData(form);
+
+    const res = await fetch('/api/upload', { method: 'POST', body: data });
+    const json = await res.json();
+
+    if (!res.ok) {
+      setStatus(`Error: ${json.error}`);
+    } else {
+      setStatus('File uploaded successfully.');
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="file" name="file" required />
+      <button type="submit">Upload</button>
+      {status && <p>{status}</p>}
+    </form>
+  );
+}
+```
+
+---
+
+## Environment variables
+
+Add to `.env.local`:
+
+```
+CLAMAV_HOST=127.0.0.1
+CLAMAV_PORT=3310
+S3_BUCKET=my-upload-bucket
+AWS_REGION=us-east-1
+```
+
+In production (Docker), set `CLAMAV_HOST` to the clamd service name (e.g. `clamav`).
+
+---
+
+## Notes
+
+- **Vercel / serverless:** ClamAV cannot be installed on Vercel's serverless functions. Use TCP mode pointing to a self-hosted clamd instance (fly.io, Railway, EC2) or switch to a dedicated scan microservice.
+- **File size limits:** Next.js has a default request body size limit (4 MB for Pages Router). Increase it via `export const config = { api: { bodyParser: { sizeLimit: '20mb' } } }` or disable parsing for multipart routes.
+- **App Router streaming:** The App Router supports streaming request bodies via `request.body` (`ReadableStream`). To use `scanStream()`, convert with `Readable.fromWeb(request.body)` (Node.js 18+).
+
+```ts
+import { Readable } from 'stream';
+const nodeStream = Readable.fromWeb(request.body as ReadableStream);
+const result = await scanStream(nodeStream, SCAN_OPTS);
+```