pompelmi 1.14.0 → 1.16.0

package/packages/remix/index.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const { scanBuffer, Verdict } = require('pompelmi');
+
+// File is a global in Node 20+; on Node 18 it lives in node:buffer
+const NodeFile = globalThis.File ?? require('node:buffer').File;
+
+const SCAN_KEYS = ['host', 'port', 'socket', 'timeout', 'retries', 'retryDelay'];
+
+function buildScanOptions(options) {
+  const out = {};
+  for (const k of SCAN_KEYS) {
+    if (options[k] !== undefined) out[k] = options[k];
+  }
+  return out;
+}
+
+async function collectStream(data) {
+  const chunks = [];
+  for await (const chunk of data) {
+    chunks.push(chunk instanceof Buffer ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Creates a Remix UploadHandler that scans each uploaded file with pompelmi
+ * before passing it to an optional inner handler.
+ *
+ * Usage in a Remix action:
+ *
+ *   import { unstable_parseMultipartFormData } from '@remix-run/node'
+ *   import { pompelmiUploadHandler } from '@pompelmi/remix'
+ *
+ *   export async function action({ request }) {
+ *     const formData = await unstable_parseMultipartFormData(
+ *       request,
+ *       pompelmiUploadHandler({ host: 'localhost', port: 3310 })
+ *     )
+ *     // file is guaranteed clean here
+ *   }
+ *
+ * @param {object}   [options]
+ * @param {string}   [options.field]           - Only scan this field; pass others through (default: scan all files).
+ * @param {Function} [options.inner]           - Inner UploadHandler for clean files. Defaults to storing as File.
+ * @param {string}   [options.host]            - clamd hostname.
+ * @param {number}   [options.port=3310]       - clamd port.
+ * @param {string}   [options.socket]          - UNIX socket path.
+ * @param {number}   [options.timeout=15000]   - Socket idle timeout in ms.
+ * @param {number}   [options.retries=0]       - Retry attempts.
+ * @param {number}   [options.retryDelay=1000] - Delay between retries in ms.
+ * @param {Function} [options.onInfected]      - Called with ({ name, filename }) when malware is detected.
+ *                                              Must throw or return a Response. Default throws HTTP 422.
+ */
+function pompelmiUploadHandler(options) {
+  const { field, inner, onInfected } = options || {};
+  const scanOptions = buildScanOptions(options || {});
+
+  return async function remixUploadHandler({ name, filename, contentType, data }) {
+    // Skip non-file fields (no filename) or fields not targeted
+    if (!filename || (field && name !== field)) {
+      if (typeof inner === 'function') {
+        return inner({ name, filename, contentType, data });
+      }
+      const buf = await collectStream(data);
+      // Text field (no filename) → return as string; file field → return as File
+      if (!filename) return buf.toString('utf8');
+      return new NodeFile([buf], filename, { type: contentType });
+    }
+
+    const buffer = await collectStream(data);
+
+    if (buffer.length > 0) {
+      const result = await scanBuffer(buffer, scanOptions);
+      if (result === Verdict.Malicious) {
+        if (typeof onInfected === 'function') {
+          return onInfected({ name, filename });
+        }
+        throw new Response(
+          JSON.stringify({ error: 'Malware detected', filename }),
+          { status: 422, headers: { 'Content-Type': 'application/json' } }
+        );
+      }
+    }
+
+    if (typeof inner === 'function') {
+      // Replay the buffer through the inner handler via an async generator
+      async function* replay() { yield buffer; }
+      return inner({ name, filename, contentType, data: replay() });
+    }
+
+    return new NodeFile([buffer], filename, { type: contentType });
+  };
+}
+
+module.exports = { pompelmiUploadHandler, Verdict };

package/packages/remix/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pompelmi/remix",
+  "version": "1.0.0",
+  "description": "Remix upload handler for pompelmi — in-process ClamAV virus scanning with zero extra dependencies",
+  "license": "ISC",
+  "author": "pompelmi contributors",
+  "homepage": "https://pompelmi.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pompelmi/pompelmi.git",
+    "directory": "packages/remix"
+  },
+  "keywords": [
+    "remix",
+    "remix-run",
+    "upload-handler",
+    "clamav",
+    "antivirus",
+    "virus-scan",
+    "malware",
+    "file-upload",
+    "security",
+    "pompelmi",
+    "fullstack"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "test": "node --test test/index.test.js"
+  },
+  "peerDependencies": {
+    "pompelmi": ">=1.15.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/packages/sveltekit/README.md

@@ -0,0 +1,138 @@
+# @pompelmi/sveltekit
+
+SvelteKit helper for [pompelmi](https://pompelmi.app) — in-process ClamAV virus scanning with zero extra dependencies.
+
+Works with both **+page.server.ts actions** and **+server.ts API routes** on Node.js.
+
+## Installation
+
+```bash
+npm install @pompelmi/sveltekit pompelmi
+```
+
+> **Requires** the [`@sveltejs/adapter-node`](https://kit.svelte.dev/docs/adapter-node) adapter. ClamAV is a Node.js process and cannot run on edge runtimes.
+
+## Quick Start
+
+### Form action (+page.server.ts)
+
+```ts
+import { scanUpload } from '@pompelmi/sveltekit'
+import type { Actions } from './$types'
+
+export const actions: Actions = {
+  default: async ({ request }) => {
+    const formData = await request.formData()
+    const file = formData.get('file') as File
+
+    // Throws HTTP 422 Response automatically if malware is detected
+    await scanUpload(file, { host: 'localhost', port: 3310 })
+
+    // File is guaranteed clean here — save to storage, etc.
+    return { success: true, name: file.name }
+  }
+}
+```
+
+If a malicious file is uploaded, `scanUpload` throws a `Response` with HTTP **422** and a JSON body `{ error: 'Malware detected', filename }`. SvelteKit's error boundary catches it automatically.
+
+### API route (+server.ts)
+
+```ts
+import { scanUpload } from '@pompelmi/sveltekit'
+import { json } from '@sveltejs/kit'
+import type { RequestHandler } from './$types'
+
+export const POST: RequestHandler = async ({ request }) => {
+  const formData = await request.formData()
+  const file = formData.get('file') as File
+
+  await scanUpload(file, { host: 'localhost', port: 3310 })
+
+  return json({ ok: true, name: file.name, size: file.size })
+}
+```
+
+## Scan all files in FormData
+
+Use `scanFormData` to scan every file field at once. Throws on the first malicious file:
+
+```ts
+import { scanFormData } from '@pompelmi/sveltekit'
+
+export const actions: Actions = {
+  default: async ({ request }) => {
+    const formData = await request.formData()
+
+    // Scans all File/Blob values; throws 422 if any is malicious
+    await scanFormData(formData, { host: 'localhost', port: 3310 })
+
+    return { success: true }
+  }
+}
+```
+
+## Custom error handling
+
+```ts
+import { scanUpload } from '@pompelmi/sveltekit'
+import { fail } from '@sveltejs/kit'
+
+export const actions: Actions = {
+  default: async ({ request }) => {
+    const formData = await request.formData()
+    const file = formData.get('file') as File
+
+    await scanUpload(file, {
+      host: 'localhost',
+      port: 3310,
+      onInfected: ({ filename }) => {
+        console.warn(`Blocked malicious upload: ${filename}`)
+        // Use SvelteKit's fail() to return a form error
+        throw fail(422, { error: `${filename} contains malware` })
+      },
+    })
+
+    return { success: true }
+  }
+}
+```
+
+## Route component example (full)
+
+```svelte
+<!-- src/routes/upload/+page.svelte -->
+<script lang="ts">
+  import { enhance } from '$app/forms'
+  import type { ActionData } from './$types'
+
+  export let form: ActionData
+</script>
+
+<form method="POST" enctype="multipart/form-data" use:enhance>
+  <input type="file" name="file" required />
+  <button type="submit">Upload & Scan</button>
+
+  {#if form?.error}
+    <p style="color: red">{form.error}</p>
+  {:else if form?.success}
+    <p>Uploaded: {form.name}</p>
+  {/if}
+</form>
+```
+
+## Configuration Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | `string` | — | clamd hostname (enables TCP mode) |
+| `port` | `number` | `3310` | clamd port |
+| `socket` | `string` | — | UNIX domain socket path |
+| `timeout` | `number` | `15000` | Socket idle timeout in ms |
+| `retries` | `number` | `0` | Retry attempts |
+| `retryDelay` | `number` | `1000` | Delay between retries in ms |
+| `onInfected` | `Function` | — | Called with `{ filename }` when malware detected; must throw |
+
+## License
+
+ISC — see root [LICENSE](../../LICENSE).

package/packages/sveltekit/index.d.ts

@@ -0,0 +1,59 @@
+import type { ScanOptions } from 'pompelmi';
+
+export interface PompelmiSvelteKitOptions extends ScanOptions {
+  /**
+   * Called with `{ filename }` when a malicious file is detected.
+   * Must throw (e.g. throw error(422, { message: 'Malware detected' })).
+   * If omitted, throws an HTTP 422 Response automatically.
+   */
+  onInfected?: (args: { filename: string }) => never | Promise<never>;
+}
+
+/**
+ * Scans an uploaded file with pompelmi inside a SvelteKit server action or
+ * API route (+page.server.ts / +server.ts). Throws HTTP 422 on malicious files.
+ *
+ * @example
+ * // +page.server.ts
+ * import { scanUpload } from '@pompelmi/sveltekit'
+ * import type { Actions } from './$types'
+ *
+ * export const actions: Actions = {
+ *   default: async ({ request }) => {
+ *     const formData = await request.formData()
+ *     await scanUpload(formData.get('file') as File, { host: 'localhost', port: 3310 })
+ *     return { success: true }
+ *   }
+ * }
+ *
+ * @example
+ * // +server.ts (API route)
+ * import { scanUpload } from '@pompelmi/sveltekit'
+ * import { json } from '@sveltejs/kit'
+ * import type { RequestHandler } from './$types'
+ *
+ * export const POST: RequestHandler = async ({ request }) => {
+ *   const formData = await request.formData()
+ *   await scanUpload(formData.get('file') as File, { host: 'localhost', port: 3310 })
+ *   return json({ ok: true })
+ * }
+ */
+export function scanUpload(
+  file: File | Blob | Buffer | null | undefined,
+  options?: PompelmiSvelteKitOptions
+): Promise<symbol>;
+
+/**
+ * Scans all File/Blob values in a FormData object.
+ * Throws HTTP 422 on the first malicious file found.
+ *
+ * @example
+ * const formData = await request.formData()
+ * await scanFormData(formData, { host: 'localhost', port: 3310 })
+ */
+export function scanFormData(
+  formData: FormData,
+  options?: PompelmiSvelteKitOptions
+): Promise<void>;
+
+export { Verdict } from 'pompelmi';

package/packages/sveltekit/index.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const { scanBuffer, Verdict } = require('pompelmi');
+
+// File is a global in Node 20+; on Node 18 it lives in node:buffer
+const NodeFile = globalThis.File ?? require('node:buffer').File;
+
+const SCAN_KEYS = ['host', 'port', 'socket', 'timeout', 'retries', 'retryDelay'];
+
+function buildScanOptions(options) {
+  const out = {};
+  for (const k of SCAN_KEYS) {
+    if (options[k] !== undefined) out[k] = options[k];
+  }
+  return out;
+}
+
+async function toBuffer(file) {
+  if (Buffer.isBuffer(file)) return file;
+  if (file instanceof Uint8Array) return Buffer.from(file);
+  // Web API File / Blob
+  if (file && typeof file.arrayBuffer === 'function') {
+    return Buffer.from(await file.arrayBuffer());
+  }
+  return null;
+}
+
+/**
+ * Scans an uploaded file with pompelmi inside a SvelteKit server action or
+ * API route. Throws an HTTP 422 Response automatically on malicious files.
+ *
+ * Use in a +page.server.ts action or +server.ts route:
+ *
+ *   import { scanUpload } from '@pompelmi/sveltekit'
+ *
+ *   export const actions = {
+ *     default: async ({ request }) => {
+ *       const formData = await request.formData()
+ *       await scanUpload(formData.get('file'), { host: 'localhost', port: 3310 })
+ *       // file is guaranteed clean here
+ *       return { success: true }
+ *     }
+ *   }
+ *
+ * @param {File|Blob|Buffer}  file                  - The uploaded file to scan.
+ * @param {object}            [options]
+ * @param {string}            [options.host]        - clamd hostname (enables TCP mode).
+ * @param {number}            [options.port=3310]   - clamd port.
+ * @param {string}            [options.socket]      - UNIX domain socket path.
+ * @param {number}            [options.timeout]     - Socket idle timeout in ms.
+ * @param {number}            [options.retries]     - Retry attempts.
+ * @param {number}            [options.retryDelay]  - Delay between retries in ms.
+ * @param {Function}          [options.onInfected]  - Called with ({ filename }) when malware
+ *                                                   is detected. Must throw. Defaults to
+ *                                                   throwing HTTP 422 Response.
+ * @returns {Promise<symbol>} Verdict.Clean or Verdict.ScanError (never returns Verdict.Malicious).
+ */
+async function scanUpload(file, options) {
+  if (!file) return Verdict.Clean;
+
+  const scanOptions = buildScanOptions(options || {});
+  const buffer = await toBuffer(file);
+
+  if (!buffer || buffer.length === 0) return Verdict.Clean;
+
+  const result = await scanBuffer(buffer, scanOptions);
+
+  if (result === Verdict.Malicious) {
+    const filename = (file && typeof file.name === 'string') ? file.name : 'upload';
+    const onInfected = options && options.onInfected;
+    if (typeof onInfected === 'function') {
+      return onInfected({ filename });
+    }
+    throw new Response(
+      JSON.stringify({ error: 'Malware detected', filename }),
+      { status: 422, headers: { 'Content-Type': 'application/json' } }
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Scans all File/Blob values in a FormData object. Throws on the first
+ * malicious file found.
+ *
+ * @param {FormData}  formData             - The parsed form data.
+ * @param {object}    [options]            - Same options as scanUpload.
+ * @returns {Promise<void>}
+ */
+async function scanFormData(formData, options) {
+  if (!formData || typeof formData.entries !== 'function') return;
+  for (const [, value] of formData.entries()) {
+    if (value instanceof NodeFile || (value && typeof value.arrayBuffer === 'function')) {
+      await scanUpload(value, options);
+    }
+  }
+}
+
+module.exports = { scanUpload, scanFormData, Verdict };

package/packages/sveltekit/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pompelmi/sveltekit",
+  "version": "1.0.0",
+  "description": "SvelteKit helper for pompelmi — in-process ClamAV virus scanning with zero extra dependencies",
+  "license": "ISC",
+  "author": "pompelmi contributors",
+  "homepage": "https://pompelmi.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pompelmi/pompelmi.git",
+    "directory": "packages/sveltekit"
+  },
+  "keywords": [
+    "sveltekit",
+    "svelte",
+    "server-action",
+    "api-route",
+    "clamav",
+    "antivirus",
+    "virus-scan",
+    "malware",
+    "file-upload",
+    "security",
+    "pompelmi"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "test": "node --test test/index.test.js"
+  },
+  "peerDependencies": {
+    "pompelmi": ">=1.15.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/packages/testing/README.md

@@ -0,0 +1,126 @@
+# @pompelmi/testing
+
+Mock utilities for unit-testing applications that use [pompelmi](https://pompelmi.app).
+
+Compatible with **Jest**, **Vitest**, and the **Node.js built-in test runner**.
+
+## Installation
+
+```bash
+npm install --save-dev @pompelmi/testing pompelmi
+```
+
+## Usage
+
+### `mockClean()` / `mockInfected()` / `mockScanError()`
+
+```js
+const { mockClean, mockInfected, mockScanError, Verdict } = require('@pompelmi/testing')
+
+it('passes clean files through', async () => {
+  const scanner = mockClean()
+  const result = await scanner.scanBuffer(Buffer.from('hello'))
+  assert.equal(result, Verdict.Clean)
+})
+
+it('rejects infected files', async () => {
+  const scanner = mockInfected('Win.Malware.Test')
+  const result = await scanner.scanBuffer(Buffer.from('eicar'))
+  assert.equal(result, Verdict.Malicious)
+  assert.equal(scanner.virusName, 'Win.Malware.Test')
+})
+
+it('handles scan errors', async () => {
+  const scanner = mockScanError()
+  const result = await scanner.scanBuffer(Buffer.from('data'))
+  assert.equal(result, Verdict.ScanError)
+})
+```
+
+### `createMockScanner(defaultVerdict)`
+
+Creates a scanner that resolves every scan call to the given verdict.
+
+```js
+const { createMockScanner, Verdict } = require('@pompelmi/testing')
+
+const scanner = createMockScanner(Verdict.Malicious)
+// scanner.scan(), scanner.scanBuffer(), scanner.scanStream() all → Verdict.Malicious
+```
+
+### `withMockedPompelmi(verdict, fn)`
+
+Convenience wrapper that creates the mock and passes it to your test function.
+
+```js
+const { withMockedPompelmi, Verdict } = require('@pompelmi/testing')
+
+it('rejects infected files', () =>
+  withMockedPompelmi(Verdict.Malicious, async (scanner) => {
+    const result = await scanner.scanBuffer(Buffer.from('eicar'))
+    assert.equal(result, Verdict.Malicious)
+  })
+)
+```
+
+## Jest Example
+
+```js
+import { mockInfected, Verdict } from '@pompelmi/testing'
+
+// Manually inject the mock scanner into a module under test
+jest.mock('pompelmi', () => mockInfected('Eicar'))
+
+test('upload handler rejects infected files', async () => {
+  const { handleUpload } = await import('./upload-handler')
+  const response = await handleUpload(evilBuffer)
+  expect(response.status).toBe(422)
+})
+```
+
+## Vitest Example
+
+```ts
+import { mockClean, Verdict } from '@pompelmi/testing'
+import { vi, it, expect } from 'vitest'
+
+vi.mock('pompelmi', () => mockClean())
+
+it('allows clean files', async () => {
+  const { handleUpload } = await import('./upload-handler')
+  const res = await handleUpload(cleanBuffer)
+  expect(res.status).toBe(200)
+})
+```
+
+## Node.js built-in test runner
+
+```js
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { mockInfected, Verdict } = require('@pompelmi/testing')
+
+describe('upload handler', () => {
+  it('rejects infected files', async () => {
+    const scanner = mockInfected('Win.Malware.Agent')
+    const result = await scanner.scanBuffer(Buffer.from('eicar'))
+    assert.equal(result, Verdict.Malicious)
+    assert.equal(scanner.virusName, 'Win.Malware.Agent')
+  })
+})
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `createMockScanner(verdict)` | Returns a mock scanner that resolves to `verdict` |
+| `mockClean()` | Shorthand for `createMockScanner(Verdict.Clean)` |
+| `mockInfected(virusName?)` | Shorthand for `createMockScanner(Verdict.Malicious)` |
+| `mockScanError()` | Shorthand for `createMockScanner(Verdict.ScanError)` |
+| `withMockedPompelmi(verdict, fn)` | Runs `fn` with a mock scanner, returns a Promise |
+| `Verdict` | Re-exported from `pompelmi` |
+
+## License
+
+ISC — see root [LICENSE](../../LICENSE).

package/packages/testing/index.d.ts

@@ -0,0 +1,44 @@
+
+export interface MockScanner {
+  Verdict: { readonly Clean: symbol; readonly Malicious: symbol; readonly ScanError: symbol };
+  scan(filePath: string): Promise<symbol>;
+  scanBuffer(buffer: Buffer | Uint8Array): Promise<symbol>;
+  scanStream(stream: NodeJS.ReadableStream): Promise<symbol>;
+  scanS3(opts: Record<string, unknown>): Promise<symbol>;
+  /** The verdict this scanner always resolves to */
+  _verdict: symbol;
+  /** Virus name label — only present on mockInfected() scanners */
+  virusName?: string;
+}
+
+/**
+ * Creates a mock pompelmi scanner where every scan method resolves to
+ * `defaultVerdict`.
+ */
+export function createMockScanner(defaultVerdict: symbol): MockScanner;
+
+/** Returns a mock scanner that always resolves to Verdict.Clean */
+export function mockClean(): MockScanner;
+
+/**
+ * Returns a mock scanner that always resolves to Verdict.Malicious.
+ * The `virusName` is stored as `scanner.virusName` for test assertions.
+ */
+export function mockInfected(virusName?: string): MockScanner;
+
+/** Returns a mock scanner that always resolves to Verdict.ScanError */
+export function mockScanError(): MockScanner;
+
+/**
+ * Wraps a test function with a mock scanner.
+ * The scanner is passed as the first argument to `fn`.
+ *
+ * @example
+ * await withMockedPompelmi(Verdict.Malicious, async (scanner) => {
+ *   const result = await scanner.scanBuffer(buffer)
+ *   expect(result).toBe(Verdict.Malicious)
+ * })
+ */
+export function withMockedPompelmi(verdict: symbol, fn: (scanner: MockScanner) => unknown): Promise<void>;
+
+export { Verdict } from 'pompelmi';