pompelmi 1.16.0 → 1.17.0

package/README.md

@@ -89,12 +89,15 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - 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
 - Built-in helpers to install ClamAV and update virus definitions programmatically
+- **Native ESM support** — `import { scan } from 'pompelmi'` works out of the box (dual CJS/ESM build)
+- **Deno support** — `import { scan } from 'npm:pompelmi'` — no install step required
+- **Cloudflare Workers** — via `@pompelmi/cloudflare` — Web APIs only, no Node.js built-ins
 - Works with Express, Fastify, NestJS, Hono, Remix, SvelteKit, and any other Node.js HTTP framework
-- Works with Node.js and Bun — uses `Bun.file()` for faster file reading when available
+- Works with **Node.js • Bun • Deno • Cloudflare Workers**
 - Interactive demo at [pompelmi.app/demo](https://pompelmi.app/demo.html) — try before you install
 - Zero runtime dependencies — ships nothing but source code
 - Tested with EICAR standard antivirus test files
-- CommonJS module; TypeScript type declarations available inline
+- CommonJS + ESM module; TypeScript type declarations available inline
 
 See [how pompelmi compares](./docs/comparison.html) to other Node.js ClamAV integrations.
 
@@ -112,6 +115,7 @@ Official integration packages for popular frameworks:
 | [@pompelmi/remix](./packages/remix/) | Remix | `npm i @pompelmi/remix` |
 | [@pompelmi/sveltekit](./packages/sveltekit/) | SvelteKit | `npm i @pompelmi/sveltekit` |
 | [@pompelmi/testing](./packages/testing/) | Jest/Vitest/Node | `npm i -D @pompelmi/testing` |
+| [@pompelmi/cloudflare](./packages/cloudflare/) | Cloudflare Workers | `npm i @pompelmi/cloudflare` |
 
 ### NestJS
 
@@ -197,6 +201,8 @@ export const actions: Actions = {
 
 - **Node.js** — any LTS release (no native addons, no C++ bindings)
 - **Bun** — fully supported; uses `Bun.file()` for faster file reading
+- **Deno** — import from `npm:pompelmi` — no install step required
+- **Cloudflare Workers** — via `@pompelmi/cloudflare` — connects to a remote clamd over TCP
 - **ClamAV** — must be installed on the host or reachable over TCP
 
 pompelmi does not bundle or automatically download ClamAV. Install it once per machine (see [Installing ClamAV](#installing-clamav)).
@@ -608,8 +614,8 @@ Please read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing. To r
 
 ## Coming soon
 
-- [ ] Cloudflare Workers support — edge-native scanning via the clamd TCP protocol
-- [ ] NestJS official module — `PompelmiModule.forRoot()` with injectable `PompelmiService`
+- [x] Cloudflare Workers support — `@pompelmi/cloudflare` ships in v1.17.0
+- [x] NestJS official module — `PompelmiModule.forRoot()` with injectable `PompelmiService`
 
 ---
 

package/deno.json

@@ -0,0 +1,5 @@
+{
+  "name": "@pompelmi/pompelmi",
+  "version": "1.17.0",
+  "exports": "./src/index.js"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.16.0",
+  "version": "1.17.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",
@@ -35,12 +35,19 @@
   ],
   "type": "commonjs",
   "main": "./src/index.js",
+  "module": "./src/index.mjs",
   "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js"
+    }
+  },
   "bin": {
     "pompelmi": "./bin/pompelmi.js"
   },
   "scripts": {
-    "test": "node --test test/unit.test.js && node --test packages/nestjs/test/index.test.js && node --test packages/fastify/test/index.test.js && node --test packages/nextjs/test/index.test.js && node --test packages/hono/test/index.test.js && node --test packages/testing/test/index.test.js && node --test packages/remix/test/index.test.js && node --test packages/sveltekit/test/index.test.js && node test/scan.test.js",
+    "test": "node --test test/unit.test.js && node --test test/esm.test.mjs && node --test packages/nestjs/test/index.test.js && node --test packages/fastify/test/index.test.js && node --test packages/nextjs/test/index.test.js && node --test packages/hono/test/index.test.js && node --test packages/testing/test/index.test.js && node --test packages/remix/test/index.test.js && node --test packages/sveltekit/test/index.test.js && node --test packages/cloudflare/test/index.test.mjs && node test/scan.test.js",
     "lint": "eslint src/"
   },
   "publishConfig": {

package/packages/cloudflare/README.md

@@ -0,0 +1,94 @@
+# @pompelmi/cloudflare
+
+Scan file uploads for malware inside **Cloudflare Workers** using a remote [ClamAV](https://www.clamav.net/) (clamd) instance.
+
+Uses Web APIs only (`fetch`, `connect` from `cloudflare:sockets`) — no Node.js built-ins, fully compatible with the Workers Runtime.
+
+## Requirements
+
+Cloudflare Workers cannot run clamd locally. You need a **publicly reachable** clamd instance. Options:
+
+- A VPS running clamd with port 3310 open (add appropriate firewall rules).
+- A Cloudflare Tunnel ([cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)) pointing to a private clamd instance.
+
+> **Security note:** Restrict clamd access to your Worker's outbound IPs or use a shared secret at the application layer. Never expose clamd directly to the public internet without access controls.
+
+## Installation
+
+```
+npm i @pompelmi/cloudflare
+```
+
+## Usage
+
+```js
+import { scanBuffer, scanRequest } from '@pompelmi/cloudflare';
+
+export default {
+  async fetch(request, env) {
+    // Option A: scan the whole multipart form at once
+    const rejection = await scanRequest(request, {
+      host: env.CLAMAV_HOST,
+      port: parseInt(env.CLAMAV_PORT),
+    });
+    if (rejection) return rejection; // 422 or 500
+
+    return new Response('File accepted');
+  },
+};
+```
+
+Or scan an `ArrayBuffer` directly:
+
+```js
+import { scanBuffer } from '@pompelmi/cloudflare';
+
+export default {
+  async fetch(request, env) {
+    const formData = await request.formData();
+    const file = formData.get('file');
+    const buffer = await file.arrayBuffer();
+
+    const result = await scanBuffer(buffer, {
+      host: env.CLAMAV_HOST,
+      port: parseInt(env.CLAMAV_PORT),
+    });
+
+    if (result !== 'clean') {
+      return new Response('File rejected', { status: 422 });
+    }
+
+    return new Response('OK');
+  },
+};
+```
+
+## API
+
+### `scanBuffer(buffer, options)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `buffer` | `ArrayBuffer` | The file bytes to scan |
+| `options.host` | `string` | clamd hostname or IP (required) |
+| `options.port` | `number` | clamd port, typically `3310` (required) |
+| `options.timeout` | `number` | Read timeout in ms (default: `15000`) |
+
+Returns `Promise<'clean' | 'malicious' | 'error'>`.
+
+### `scanRequest(request, options)`
+
+Reads the multipart form field (default: `file`), scans it, and returns:
+- `null` — file is clean, proceed normally.
+- `Response(422)` — malicious file detected.
+- `Response(500)` — scan error (clamd unreachable, timeout, etc.).
+
+Additional option: `options.field` — form field name (default: `'file'`).
+
+## Wrangler configuration
+
+Copy [`wrangler.toml.example`](./wrangler.toml.example) to `wrangler.toml` and fill in your clamd host details.
+
+## License
+
+ISC

package/packages/cloudflare/index.d.ts

@@ -0,0 +1,50 @@
+/** Result returned by scanBuffer */
+export type ScanResult = 'clean' | 'malicious' | 'error';
+
+/** Options for connecting to a remote clamd instance */
+export interface CloudflareScanOptions {
+  /** Hostname or IP of the remote clamd instance */
+  host: string;
+  /** Port the remote clamd listens on (typically 3310) */
+  port: number;
+  /** Socket read timeout in milliseconds (default: 15000) */
+  timeout?: number;
+  /** Form field name to scan when using scanRequest (default: 'file') */
+  field?: string;
+}
+
+/**
+ * Scan an ArrayBuffer with a remote clamd instance using INSTREAM protocol.
+ * Uses Cloudflare's `connect()` socket API — no Node.js built-ins required.
+ *
+ * @example
+ * const result = await scanBuffer(await file.arrayBuffer(), {
+ *   host: env.CLAMAV_HOST,
+ *   port: parseInt(env.CLAMAV_PORT),
+ * });
+ */
+export declare function scanBuffer(
+  buffer: ArrayBuffer,
+  options: CloudflareScanOptions
+): Promise<ScanResult>;
+
+/**
+ * Scan a multipart form field from a Cloudflare Worker Request.
+ * Returns null if the file is clean, or an HTTP Response (422/500) otherwise.
+ *
+ * @example
+ * export default {
+ *   async fetch(request, env) {
+ *     const rejection = await scanRequest(request, {
+ *       host: env.CLAMAV_HOST,
+ *       port: parseInt(env.CLAMAV_PORT),
+ *     });
+ *     if (rejection) return rejection;
+ *     return new Response('OK');
+ *   }
+ * }
+ */
+export declare function scanRequest(
+  request: Request,
+  options: CloudflareScanOptions
+): Promise<Response | null>;

package/packages/cloudflare/index.js

@@ -0,0 +1,116 @@
+/**
+ * @pompelmi/cloudflare
+ *
+ * Connects to a remote clamd instance over TCP using Cloudflare's socket API.
+ * Uses Web APIs only — no Node.js built-ins.
+ *
+ * Requires `connect` from `cloudflare:sockets` (available in Workers Runtime ≥ 2023-03-01).
+ */
+
+const INSTREAM_CHUNK = 4096; // bytes per INSTREAM chunk
+const CLEAN_RESPONSE = /^stream: OK/;
+const MALICIOUS_RESPONSE = /^stream: (.+) FOUND/;
+
+/**
+ * Send a Buffer or ArrayBuffer to clamd via INSTREAM and return the raw
+ * response string.
+ *
+ * @param {ArrayBuffer} data
+ * @param {{ host: string, port: number, timeout?: number }} options
+ * @returns {Promise<string>}
+ */
+async function clamdInstream(data, { host, port, timeout = 15000 }) {
+  // eslint-disable-next-line no-undef
+  const { connect } = await import('cloudflare:sockets');
+  const socket = connect({ hostname: host, port });
+
+  const writer = socket.writable.getWriter();
+  const reader = socket.readable.getReader();
+
+  const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+
+  // Write INSTREAM command
+  const cmd = new TextEncoder().encode('zINSTREAM\0');
+  await writer.write(cmd);
+
+  // Stream data in chunks with 4-byte big-endian length prefix
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const end = Math.min(offset + INSTREAM_CHUNK, bytes.byteLength);
+    const chunk = bytes.subarray(offset, end);
+    const lenBuf = new ArrayBuffer(4);
+    new DataView(lenBuf).setUint32(0, chunk.byteLength, false);
+    await writer.write(new Uint8Array(lenBuf));
+    await writer.write(chunk);
+    offset = end;
+  }
+
+  // Write zero-length chunk to signal end of stream
+  const terminator = new Uint8Array([0, 0, 0, 0]);
+  await writer.write(terminator);
+  writer.releaseLock();
+
+  // Read response with timeout
+  const timeoutId = setTimeout(() => reader.cancel(), timeout);
+  let response = '';
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      response += decoder.decode(value, { stream: true });
+      if (response.includes('\n') || response.includes('\0')) break;
+    }
+  } finally {
+    clearTimeout(timeoutId);
+    reader.releaseLock();
+  }
+
+  await socket.close();
+  return response.trim().replace(/\0/g, '');
+}
+
+/**
+ * Scan an ArrayBuffer with a remote clamd instance.
+ *
+ * @param {ArrayBuffer} buffer
+ * @param {{ host: string, port: number, timeout?: number }} options
+ * @returns {Promise<'clean' | 'malicious' | 'error'>}
+ */
+export async function scanBuffer(buffer, options) {
+  if (!options || !options.host || !options.port) {
+    throw new Error('@pompelmi/cloudflare: options.host and options.port are required');
+  }
+  try {
+    const response = await clamdInstream(buffer, options);
+    if (CLEAN_RESPONSE.test(response)) return 'clean';
+    if (MALICIOUS_RESPONSE.test(response)) return 'malicious';
+    return 'error';
+  } catch {
+    return 'error';
+  }
+}
+
+/**
+ * Convenience Cloudflare Worker handler that reads a multipart form field,
+ * scans it, and returns HTTP 422 on malicious files.
+ *
+ * @param {Request} request
+ * @param {{ host: string, port: number, field?: string, timeout?: number }} options
+ * @returns {Promise<Response | null>} null if clean, Response if malicious/error
+ */
+export async function scanRequest(request, options) {
+  const field = options.field || 'file';
+  const formData = await request.formData();
+  const file = formData.get(field);
+  if (!file) return null;
+  const buffer = await file.arrayBuffer();
+  const result = await scanBuffer(buffer, options);
+  if (result === 'malicious') {
+    return new Response('File rejected: malicious content detected', { status: 422 });
+  }
+  if (result === 'error') {
+    return new Response('Scan error', { status: 500 });
+  }
+  return null;
+}

package/packages/cloudflare/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pompelmi/cloudflare",
+  "version": "1.0.0",
+  "description": "pompelmi adapter for Cloudflare Workers — scan file uploads via a remote clamd instance using Web APIs only.",
+  "license": "ISC",
+  "author": "pompelmi contributors",
+  "homepage": "https://pompelmi.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pompelmi/pompelmi.git",
+    "directory": "packages/cloudflare"
+  },
+  "bugs": {
+    "url": "https://github.com/pompelmi/pompelmi/issues"
+  },
+  "keywords": [
+    "clamav",
+    "antivirus",
+    "virus-scan",
+    "malware",
+    "cloudflare",
+    "cloudflare-workers",
+    "file-upload",
+    "security"
+  ],
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/packages/cloudflare/wrangler.toml.example

@@ -0,0 +1,13 @@
+name = "my-worker"
+main = "src/worker.js"
+compatibility_date = "2024-01-01"
+
+[vars]
+CLAMAV_HOST = "your-clamd-host.example.com"
+CLAMAV_PORT = "3310"
+
+# Cloudflare Workers require a publicly reachable clamd instance.
+# Options:
+#   1. Run clamd on a VPS and expose port 3310 (add firewall rules).
+#   2. Use a Cloudflare Tunnel (cloudflared) to expose a private clamd instance.
+#      See: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/

package/src/index.mjs

@@ -0,0 +1,19 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const pompelmi = require('./index.js');
+export const {
+  scan,
+  scanBuffer,
+  scanStream,
+  scanDirectory,
+  scanS3,
+  createPool,
+  watch,
+  middleware,
+  createScanner,
+  generateDashboard,
+  generateShareCard,
+  notify,
+  Verdict,
+} = pompelmi;
+export default pompelmi;