pompelmi 1.13.0 → 1.15.0

package/README.md

@@ -73,6 +73,9 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 ## Features
 
 - Standalone CLI — scan files from any terminal with `npx pompelmi scan`
+- HTML security dashboard — generate beautiful scan reports with `--report` ([docs](./docs/dashboard.html))
+- SVG share card — shareable scan result card with `--share-card` ([docs](./docs/dashboard.html#share-card))
+- GitHub App — one-click installation for organizations, zero-config PR scanning ([docs](./docs/github-app.html))
 - Single `scan(filePath, [options])` function — works locally or against a remote clamd instance
 - `scanBuffer(buffer, [options])` — scan in-memory Buffers directly, no temp file required in TCP mode
 - `scanStream(stream, [options])` — scan a Readable stream directly. In TCP mode, streamed to clamd with no disk I/O.
@@ -86,11 +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
-- Works with Express, Fastify, NestJS, and any other Node.js HTTP framework
+- Works with Express, Fastify, NestJS, Hono, and any other Node.js HTTP framework
+- Works with Node.js and Bun — uses `Bun.file()` for faster file reading when available
+- 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
 
+See [how pompelmi compares](./docs/comparison.html) to other Node.js ClamAV integrations.
+
 ---
 
 ## Framework Integrations
@@ -101,6 +108,8 @@ Official integration packages for popular frameworks:
 |---------|-----------|---------|
 | [@pompelmi/nestjs](./packages/nestjs/) | NestJS | `npm i @pompelmi/nestjs` |
 | [@pompelmi/fastify](./packages/fastify/) | Fastify | `npm i @pompelmi/fastify` |
+| [@pompelmi/hono](./packages/hono/) | Hono | `npm i @pompelmi/hono` |
+| [@pompelmi/testing](./packages/testing/) | Jest/Vitest/Node | `npm i -D @pompelmi/testing` |
 
 ### NestJS
 
@@ -129,11 +138,29 @@ const result = await fastify.pompelmi.scanBuffer(buffer);
 fastify.post('/upload', { preHandler: fastify.pompelmi.preHandler({ field: 'file' }) }, handler);
 ```
 
+### Hono (Node.js, Bun, Cloudflare Workers)
+
+```js
+import { Hono } from 'hono'
+import { pompelmiMiddleware } from '@pompelmi/hono'
+
+const app = new Hono()
+
+app.use('/upload/*', pompelmiMiddleware({
+  host: 'localhost',
+  port: 3310,
+  onInfected: (c, filename) => c.json({ error: 'Malware detected' }, 422),
+}))
+
+app.post('/upload', async (c) => c.json({ ok: true }))
+```
+
 ---
 
 ## Requirements
 
 - **Node.js** — any LTS release (no native addons, no C++ bindings)
+- **Bun** — fully supported; uses `Bun.file()` for faster file reading
 - **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)).
@@ -153,6 +180,9 @@ yarn add pompelmi
 
 # pnpm
 pnpm add pompelmi
+
+# bun
+bun add pompelmi
 ```
 
 ### Docker
@@ -503,6 +533,8 @@ Scan any repository for viruses on every push or pull request — ClamAV is bund
 
 A ready-to-copy workflow is available at [`.github/workflows/action-example.yml`](./.github/workflows/action-example.yml). Full reference — inputs, outputs, layer caching, and more examples — in **[docs/github-action.md](./docs/github-action.md)**.
 
+> **For organizations:** install the [pompelmi GitHub App](./docs/github-app.html) for zero-config scanning on every PR — no workflow file needed.
+
 ---
 
 ## Contributing

package/bin/pompelmi.js

@@ -67,6 +67,10 @@ function parseArgs(argv) {
     quiet: false,
     delete: false,
     recursive: true,
+    report: false,
+    reportOutput: null,
+    shareCard: false,
+    shareCardOutput: null,
   };
 
   let i = 0;
@@ -92,6 +96,14 @@ function parseArgs(argv) {
       opts.timeout = parseInt(args[++i], 10);
     } else if (a === '--retries') {
       opts.retries = parseInt(args[++i], 10);
+    } else if (a === '--report') {
+      opts.report = true;
+    } else if (a === '--share-card') {
+      opts.shareCard = true;
+    } else if (a === '--output') {
+      const next = args[++i];
+      if (next && next.endsWith('.svg')) opts.shareCardOutput = next;
+      else opts.reportOutput = next;
     } else if (!a.startsWith('-') && opts.command && !opts.target) {
       opts.target = a;
     }
@@ -276,6 +288,26 @@ async function cmdScan(opts) {
 
   printResults(results, elapsed, opts);
 
+  if (opts.report) {
+    const { generateDashboard } = require('../src/Dashboard.js');
+    const outPath = opts.reportOutput || 'pompelmi-report.html';
+    generateDashboard(results, {
+      elapsed,
+      host: opts.host,
+      port: opts.port,
+      socket: opts.socket,
+      outputPath: outPath,
+    });
+    if (!opts.quiet) console.log(`\n  Report saved: ${outPath}`);
+  }
+
+  if (opts.shareCard) {
+    const { generateShareCard } = require('../src/ShareCard.js');
+    const outPath = opts.shareCardOutput || 'pompelmi-scan-card.svg';
+    generateShareCard(results, { outputPath: outPath });
+    if (!opts.quiet) console.log(`  Share card saved: ${outPath}`);
+  }
+
   const hasInfected = results.some(r => r.verdict === 'infected');
   const hasError    = results.some(r => r.verdict === 'error');
   const clamdDown   = results.some(r => r._clamdUnreachable);
@@ -361,6 +393,10 @@ SCAN OPTIONS
   --json             Output results as JSON (no logo, no colors)
   --quiet, -q        Only print infected files and summary
   --delete           Delete infected files after confirmation
+  --report           Generate an HTML security dashboard report
+  --share-card       Generate a shareable SVG scan result card
+  --output <file>    Output path for --report (default: pompelmi-report.html)
+                     or --share-card (default: pompelmi-scan-card.svg)
 
 WATCH OPTIONS
   --host, --port, --socket, --timeout   (same as scan)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.13.0",
+  "version": "1.15.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",
@@ -37,7 +37,7 @@
     "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/scan.test.js",
+    "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/scan.test.js",
     "lint": "eslint src/"
   },
   "publishConfig": {

package/packages/hono/README.md

@@ -0,0 +1,160 @@
+# @pompelmi/hono
+
+Hono middleware for [pompelmi](https://pompelmi.app) — in-process ClamAV virus scanning with zero extra dependencies.
+
+Works on **Node.js**, **Bun**, and **Cloudflare Workers** (simulation mode).
+
+## Installation
+
+```bash
+npm install @pompelmi/hono pompelmi
+# or
+bun add @pompelmi/hono pompelmi
+```
+
+## Quick Start
+
+```js
+import { Hono } from 'hono'
+import { pompelmiMiddleware } from '@pompelmi/hono'
+
+const app = new Hono()
+
+app.use('/upload/*', pompelmiMiddleware({
+  host: 'localhost',
+  port: 3310,
+}))
+
+app.post('/upload', async (c) => {
+  // file is guaranteed clean here
+  return c.json({ ok: true })
+})
+
+export default app
+```
+
+## Custom infected handler
+
+```js
+app.use('/upload/*', pompelmiMiddleware({
+  host: 'localhost',
+  port: 3310,
+  field: 'file',
+  onInfected: (c, filename) => {
+    console.warn(`Blocked malicious upload: ${filename}`)
+    return c.json({ error: 'Malware detected', filename }, 422)
+  },
+}))
+```
+
+## Hono on Node.js
+
+```js
+const { serve } = require('@hono/node-server')
+const { Hono } = require('hono')
+const { pompelmiMiddleware } = require('@pompelmi/hono')
+
+const app = new Hono()
+
+app.use('/upload/*', pompelmiMiddleware({
+  host: '127.0.0.1',
+  port: 3310,
+}))
+
+app.post('/upload', async (c) => {
+  const body = await c.req.parseBody()
+  const file = body['file']
+  return c.json({ name: file.name, size: file.size, ok: true })
+})
+
+serve({ fetch: app.fetch, port: 3000 }, () => {
+  console.log('Server running on http://localhost:3000')
+})
+```
+
+## Hono on Bun
+
+```ts
+import { Hono } from 'hono'
+import { pompelmiMiddleware } from '@pompelmi/hono'
+
+const app = new Hono()
+
+app.use('/upload/*', pompelmiMiddleware({
+  socket: '/run/clamav/clamd.sock',  // UNIX socket — faster on Bun
+}))
+
+app.post('/upload', async (c) => {
+  return c.json({ ok: true })
+})
+
+export default {
+  port: 3000,
+  fetch: app.fetch,
+}
+```
+
+## Hono on Cloudflare Workers
+
+> Note: clamd is not available inside Workers. Use pompelmi in a Node.js / Bun sidecar
+> service and call it over HTTP, or use the UNIX socket approach with a co-located daemon.
+>
+> For Workers deployments without a sidecar, the middleware skips scanning gracefully
+> and calls `next()` — you can gate the behaviour with an environment variable.
+
+```ts
+import { Hono } from 'hono'
+import { pompelmiMiddleware } from '@pompelmi/hono'
+
+const app = new Hono<{ Bindings: { SCAN_HOST: string; SCAN_PORT: string } }>()
+
+app.use('/upload/*', async (c, next) => {
+  if (!c.env.SCAN_HOST) return next()   // skip if no clamd configured
+  return pompelmiMiddleware({
+    host: c.env.SCAN_HOST,
+    port: Number(c.env.SCAN_PORT) || 3310,
+  })(c, next)
+})
+
+app.post('/upload', async (c) => {
+  return c.json({ ok: true })
+})
+
+export default app
+```
+
+## Configuration Reference
+
+All options are forwarded to pompelmi's `ScanOptions`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `field` | `string` | `'file'` | Form field name containing the uploaded file |
+| `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` | Number of retry attempts |
+| `retryDelay` | `number` | `1000` | Delay between retries in ms |
+| `onInfected` | `Function` | — | Called with `(c, filename)` when malware is detected |
+
+## TypeScript
+
+```ts
+import { Hono } from 'hono'
+import { pompelmiMiddleware } from '@pompelmi/hono'
+import { Verdict } from 'pompelmi'
+
+const app = new Hono()
+
+app.use('/upload/*', pompelmiMiddleware({
+  host: 'localhost',
+  port: 3310,
+  onInfected: (c, filename) =>
+    c.json({ error: `${filename} is infected` }, 422),
+}))
+```
+
+## License
+
+ISC — see root [LICENSE](../../LICENSE).

package/packages/hono/index.d.ts

@@ -0,0 +1,29 @@
+import type { MiddlewareHandler, Context } from 'hono';
+import type { ScanOptions } from 'pompelmi';
+
+export interface PompelmiHonoOptions extends ScanOptions {
+  /** Form field name that contains the uploaded file (default: 'file') */
+  field?: string;
+  /**
+   * Called with (c, filename) when a malicious file is detected.
+   * Must return a Response (or Promise<Response>).
+   * If omitted, responds with HTTP 422 { error: 'Malware detected' }.
+   */
+  onInfected?: (c: Context, filename: string) => Response | Promise<Response>;
+}
+
+/**
+ * Hono middleware that scans an uploaded file before the route handler runs.
+ * Reads the file from the parsed multipart body field (default: 'file').
+ *
+ * @example
+ * import { Hono } from 'hono'
+ * import { pompelmiMiddleware } from '@pompelmi/hono'
+ *
+ * const app = new Hono()
+ * app.use('/upload/*', pompelmiMiddleware({ host: 'localhost', port: 3310 }))
+ * app.post('/upload', (c) => c.json({ ok: true }))
+ */
+export function pompelmiMiddleware(options?: PompelmiHonoOptions): MiddlewareHandler;
+
+export { Verdict } from 'pompelmi';

package/packages/hono/index.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const { scanBuffer, Verdict } = require('pompelmi');
+
+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(raw) {
+  if (Buffer.isBuffer(raw)) return raw;
+  if (raw instanceof Uint8Array) return Buffer.from(raw);
+  // Web API File / Blob (Hono on Bun, Cloudflare Workers, Node 20+)
+  if (raw && typeof raw.arrayBuffer === 'function') {
+    return Buffer.from(await raw.arrayBuffer());
+  }
+  if (typeof raw === 'string') return Buffer.from(raw);
+  return null;
+}
+
+/**
+ * Hono middleware that scans an uploaded file with pompelmi before the route
+ * handler runs.  The file is read from the parsed multipart body.
+ *
+ * @param {object}  [options]
+ * @param {string}  [options.field='file']      - Form field name containing the file.
+ * @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=15000]     - Socket idle timeout in ms.
+ * @param {number}  [options.retries=0]         - Number of retry attempts.
+ * @param {number}  [options.retryDelay=1000]   - Delay between retries in ms.
+ * @param {Function} [options.onInfected]       - Called with (c, filename) when malware
+ *                                               is detected; must return a Response.
+ *                                               Defaults to 422 JSON error.
+ */
+function pompelmiMiddleware(options) {
+  const { field = 'file', onInfected } = options || {};
+  const scanOptions = buildScanOptions(options || {});
+
+  return async function pompelmiHonoMiddleware(c, next) {
+    let body;
+    try {
+      body = await c.req.parseBody();
+    } catch {
+      return next();
+    }
+
+    const raw = body[field];
+    if (raw == null) return next();
+
+    const buffer = await toBuffer(raw);
+    if (!buffer || buffer.length === 0) return next();
+
+    const result = await scanBuffer(buffer, scanOptions);
+
+    if (result === Verdict.Malicious) {
+      const filename = (raw && typeof raw.name === 'string') ? raw.name : field;
+      if (typeof onInfected === 'function') {
+        return onInfected(c, filename);
+      }
+      return c.json({ error: 'Malware detected' }, 422);
+    }
+
+    return next();
+  };
+}
+
+module.exports = { pompelmiMiddleware, Verdict };

package/packages/hono/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pompelmi/hono",
+  "version": "1.0.0",
+  "description": "Hono middleware 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/hono"
+  },
+  "keywords": [
+    "hono",
+    "middleware",
+    "clamav",
+    "antivirus",
+    "virus-scan",
+    "malware",
+    "file-upload",
+    "security",
+    "pompelmi",
+    "bun",
+    "edge",
+    "cloudflare-workers"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "test": "node --test test/index.test.js"
+  },
+  "peerDependencies": {
+    "hono": ">=3",
+    "pompelmi": ">=1.14.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/packages/nextjs/README.md

@@ -0,0 +1,83 @@
+# @pompelmi/nextjs
+
+Next.js middleware for [pompelmi](https://pompelmi.app) — in-process ClamAV virus scanning with zero extra dependencies.
+
+Supports both the **App Router** (Next.js 13+) and the **Pages Router** (Next.js ≤ 12).
+
+## Installation
+
+```bash
+npm install pompelmi @pompelmi/nextjs
+```
+
+ClamAV must be available on the server — either via the system `clamscan` binary or a running `clamd` daemon.
+
+## App Router (Next.js 13+)
+
+```js
+// app/api/upload/route.js
+import { withPompelmi } from '@pompelmi/nextjs'
+
+export const POST = withPompelmi(async (req) => {
+  const formData = await req.formData()
+  const file = formData.get('file')
+  // req.pompelmiVerdict is set — Verdict.Clean is guaranteed here
+  return Response.json({ ok: true })
+}, {
+  host: 'localhost',
+  port: 3310,
+})
+```
+
+With TypeScript:
+
+```ts
+// app/api/upload/route.ts
+import { withPompelmi } from '@pompelmi/nextjs'
+
+export const POST = withPompelmi(async (req: Request) => {
+  return Response.json({ ok: true })
+}, { host: 'localhost', port: 3310 })
+```
+
+## Pages Router (Next.js ≤ 12)
+
+```js
+// pages/api/upload.js
+import { withPompelmiHandler } from '@pompelmi/nextjs'
+
+async function handler(req, res) {
+  // req.pompelmiVerdict is set — Verdict.Clean is guaranteed here
+  res.json({ ok: true })
+}
+
+export default withPompelmiHandler(handler, {
+  host: 'localhost',
+  port: 3310,
+})
+```
+
+## Options
+
+All options are forwarded to `pompelmi.scanBuffer()`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `host` | `string` | — | clamd hostname (TCP mode) |
+| `port` | `number` | `3310` | clamd port |
+| `socket` | `string` | — | UNIX socket path |
+| `timeout` | `number` | `15000` | Connection timeout in ms |
+| `retries` | `number` | `0` | Auto-retry count on failure |
+
+When neither `host` nor `socket` is provided, pompelmi falls back to the local `clamscan` binary.
+
+## Behaviour
+
+- The raw request body is buffered and scanned **before** your handler runs.
+- If the body is malicious, a **400 JSON** response is returned immediately: `{ "error": "Malicious file detected" }`.
+- `req.pompelmiVerdict` is set to the `Verdict` symbol so your handler can inspect it if needed.
+- Scan errors (e.g. clamd unreachable) are **not** blocking — the request proceeds with `Verdict.ScanError`.
+
+## License
+
+ISC

package/packages/nextjs/index.d.ts

@@ -0,0 +1,45 @@
+import type { VerdictValue, ScanOptions } from 'pompelmi';
+
+/** Options accepted by withPompelmi / withPompelmiHandler */
+export interface PompelmiNextOptions extends ScanOptions {}
+
+/**
+ * App Router (Next.js 13+) wrapper.
+ * Scans the raw request body before the handler runs.
+ * Returns HTTP 400 if the body is malicious.
+ *
+ * @example
+ * // app/api/upload/route.ts
+ * import { withPompelmi } from '@pompelmi/nextjs'
+ *
+ * export const POST = withPompelmi(async (req) => {
+ *   return Response.json({ ok: true })
+ * }, { host: 'localhost', port: 3310 })
+ */
+export declare function withPompelmi(
+  handler: (req: Request, ctx?: unknown) => Promise<Response>,
+  options?: PompelmiNextOptions
+): (req: Request, ctx?: unknown) => Promise<Response>;
+
+/**
+ * Pages Router (Next.js ≤ 12) wrapper.
+ * Scans the raw request body before the handler runs.
+ * Sends HTTP 400 if the body is malicious.
+ *
+ * @example
+ * // pages/api/upload.ts
+ * import { withPompelmiHandler } from '@pompelmi/nextjs'
+ * import type { NextApiRequest, NextApiResponse } from 'next'
+ *
+ * async function handler(req: NextApiRequest, res: NextApiResponse) {
+ *   res.json({ ok: true })
+ * }
+ *
+ * export default withPompelmiHandler(handler, { host: 'localhost', port: 3310 })
+ */
+export declare function withPompelmiHandler(
+  handler: (req: import('http').IncomingMessage, res: import('http').ServerResponse) => void | Promise<void>,
+  options?: PompelmiNextOptions
+): (req: import('http').IncomingMessage, res: import('http').ServerResponse) => Promise<void>;
+
+export { Verdict } from 'pompelmi';