pompelmi 1.16.0 → 1.18.0

package/README.md

@@ -11,6 +11,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/dw/pompelmi" alt="weekly downloads"></a>
+  <a href="https://hub.docker.com/r/pompelmi/scanner"><img src="https://img.shields.io/docker/pulls/pompelmi/scanner" alt="Docker Pulls"></a>
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
   <img src="https://img.shields.io/badge/license-ISC-blue" alt="license">
   <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml"><img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -73,6 +74,10 @@ 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`
+- **Official Docker image** — `pompelmi/scanner` on Docker Hub: ClamAV + HTTP scan API in one pull ([docs](./docs/docker-image.html))
+- **Security scorecard** — grade your upload security A–F with `npx pompelmi scorecard` ([docs](./docs/scorecard.html))
+- **VS Code extension** — scan files directly from the IDE (scaffold in `packages/vscode/`) ([docs](./docs/vscode.html))
+- **Quarantine mode** — `watch ./uploads --quarantine ./quarantine` auto-moves infected files with sidecar JSON
 - 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))
@@ -89,12 +94,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 +120,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 +206,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 +619,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/bin/pompelmi.js

@@ -71,12 +71,14 @@ function parseArgs(argv) {
     reportOutput: null,
     shareCard: false,
     shareCardOutput: null,
+    quarantine: null,
+    scorecardConfig: null,
   };
 
   let i = 0;
   while (i < args.length) {
     const a = args[i];
-    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help') {
+    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help' || a === 'scorecard') {
       opts.command = a;
     } else if (a === '--json') {
       opts.json = true;
@@ -104,6 +106,10 @@ function parseArgs(argv) {
       const next = args[++i];
       if (next && next.endsWith('.svg')) opts.shareCardOutput = next;
       else opts.reportOutput = next;
+    } else if (a === '--quarantine') {
+      opts.quarantine = args[++i];
+    } else if (a === '--config') {
+      opts.scorecardConfig = args[++i];
     } else if (!a.startsWith('-') && opts.command && !opts.target) {
       opts.target = a;
     }
@@ -333,7 +339,9 @@ async function cmdWatch(opts) {
   if (!opts.json && !opts.quiet) await printLogo();
 
   const { watch } = require('../src/Watcher.js');
-  const scanOpts = buildScanOpts(opts);
+  const quarantineDir = opts.quarantine ? path.resolve(opts.quarantine) : null;
+  const watchOpts = { ...buildScanOpts(opts) };
+  if (quarantineDir) watchOpts.quarantine = quarantineDir;
 
   let scanned = 0, clean = 0, infected = 0;
 
@@ -345,7 +353,7 @@ async function cmdWatch(opts) {
 
   status();
 
-  watch(target, scanOpts, {
+  watch(target, watchOpts, {
     onClean(fp) {
       scanned++; clean++;
       if (!opts.quiet) process.stdout.write(`\n\x1b[32m✅ CLEAN\x1b[0m  ${fp}\n`);
@@ -354,6 +362,7 @@ async function cmdWatch(opts) {
     onMalicious(fp) {
       scanned++; infected++;
       process.stdout.write(`\n\x1b[31m🚨 INFECTED\x1b[0m  ${fp}\n`);
+      if (quarantineDir && !opts.quiet) process.stdout.write(`   Quarantined to ${quarantineDir}\n`);
       status();
     },
     onError(err) {
@@ -366,6 +375,44 @@ async function cmdWatch(opts) {
   process.on('SIGINT', () => { process.stdout.write('\n'); process.exit(0); });
 }
 
+async function cmdScorecard(opts) {
+  let config = {};
+  if (opts.scorecardConfig) {
+    const cfgPath = path.resolve(opts.scorecardConfig);
+    if (!fs.existsSync(cfgPath)) {
+      console.error(`Error: config file not found: ${cfgPath}`);
+      process.exit(2);
+    }
+    config = require(cfgPath);
+  }
+
+  const { generateScorecard } = require('../src/Scorecard.js');
+  const scorecard = await generateScorecard(config);
+
+  const gradeColor = { A: '\x1b[32m', B: '\x1b[32m', C: '\x1b[33m', D: '\x1b[33m', F: '\x1b[31m' };
+  const color = gradeColor[scorecard.grade] || '\x1b[0m';
+  const reset = '\x1b[0m';
+
+  if (!opts.quiet) await printLogo();
+
+  console.log(`\n  Upload Security Scorecard\n`);
+  console.log(`  Grade: ${color}${scorecard.grade}${reset}   Score: ${scorecard.score}/100\n`);
+
+  for (const f of scorecard.findings) {
+    const icon = f.status === 'pass' ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    console.log(`  ${icon}  ${f.check.padEnd(40)} (weight: ${f.weight})`);
+  }
+
+  if (scorecard.recommendations.length > 0) {
+    console.log(`\n  Recommendations:`);
+    for (const r of scorecard.recommendations) {
+      console.log(`    • ${r}`);
+    }
+  }
+
+  console.log('');
+}
+
 function cmdVersion() {
   console.log(pkg.version);
 }
@@ -380,6 +427,7 @@ USAGE
 COMMANDS
   scan <file|dir>    Scan a file or directory for viruses
   watch <dir>        Watch a directory and auto-scan new/modified files
+  scorecard          Grade your upload security configuration (A-F)
   version            Print version number
   help               Show this help message
 
@@ -400,6 +448,10 @@ SCAN OPTIONS
 
 WATCH OPTIONS
   --host, --port, --socket, --timeout   (same as scan)
+  --quarantine <dir>  Move infected files to this directory (auto-created)
+
+SCORECARD OPTIONS
+  --config <file>     Path to a pompelmi.config.js file with your upload config
 
 EXIT CODES
   0   All files clean
@@ -428,6 +480,12 @@ EXAMPLES
 
   # Use with npx (no install required)
   npx pompelmi scan ./uploads
+
+  # Watch a directory with quarantine
+  pompelmi watch ./uploads --quarantine ./quarantine
+
+  # Grade your upload security config
+  npx pompelmi scorecard --config ./pompelmi.config.js
 `);
 }
 
@@ -456,6 +514,11 @@ async function main() {
     await cmdWatch(opts);
     return;
   }
+
+  if (opts.command === 'scorecard') {
+    await cmdScorecard(opts);
+    return;
+  }
 }
 
 main().catch(err => {

package/deno.json

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

package/docker/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      clamav clamav-freshclam curl && \
+    rm -rf /var/lib/apt/lists/* && \
+    sed -i 's/^Example/#Example/' /etc/clamav/freshclam.conf && \
+    mkdir -p /var/lib/clamav /run/clamav /uploads
+
+WORKDIR /app
+RUN npm install -g pompelmi
+
+COPY docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 3310 8080
+
+ENTRYPOINT ["/entrypoint.sh"]

package/docker/README.md

@@ -0,0 +1,62 @@
+# pompelmi/scanner Docker Image
+
+Official Docker image for pompelmi — ClamAV antivirus scanning for Node.js.
+
+The image ships with:
+- ClamAV + clamd pre-installed
+- freshclam for automatic definition updates on startup
+- A minimal HTTP API server on port 8080
+
+## Quick start
+
+```bash
+docker pull pompelmi/scanner
+docker run -p 8080:8080 pompelmi/scanner
+```
+
+## Scan a file
+
+```bash
+curl -F "file=@./document.pdf" http://localhost:8080/scan
+```
+
+Response:
+
+```json
+{ "verdict": "clean", "file": "document.pdf", "viruses": [] }
+```
+
+For an infected file the verdict is `"malicious"`.
+
+## Endpoints
+
+| Method | Path      | Description                                             |
+|--------|-----------|---------------------------------------------------------|
+| POST   | /scan     | Accepts `multipart/form-data` with a `file` field. Returns `{ verdict, file, viruses }` |
+| GET    | /health   | Returns `{ status: "ok", clamd: "running" }` |
+| GET    | /stats    | Returns scan statistics (total, clean, infected, errors, uptime) |
+
+## Docker Compose
+
+```yaml
+services:
+  pompelmi:
+    image: pompelmi/scanner
+    ports:
+      - "8080:8080"
+    volumes:
+      - /uploads:/uploads
+    restart: unless-stopped
+```
+
+## Environment
+
+The container exposes two ports:
+- **8080** — HTTP scan API
+- **3310** — clamd TCP socket (for direct clamd connections from other containers)
+
+## Building locally
+
+```bash
+docker build -f docker/Dockerfile -t pompelmi/scanner .
+```

package/docker/entrypoint.sh

@@ -0,0 +1,148 @@
+#!/bin/sh
+set -e
+
+# ── Update ClamAV virus definitions ──────────────────────────────────────────
+echo "[pompelmi] Updating ClamAV definitions via freshclam..."
+freshclam --quiet || echo "[pompelmi] freshclam failed — continuing with existing definitions"
+
+# ── Start clamd in background ─────────────────────────────────────────────────
+echo "[pompelmi] Starting clamd..."
+clamd &
+CLAMD_PID=$!
+
+# Wait for clamd socket/port to be ready
+echo "[pompelmi] Waiting for clamd to be ready..."
+for i in $(seq 1 30); do
+  if clamdscan --no-summary /dev/null 2>/dev/null; then
+    echo "[pompelmi] clamd is ready"
+    break
+  fi
+  sleep 1
+done
+
+# ── Stats counters (stored in files for simplicity) ───────────────────────────
+STATS_DIR=/tmp/pompelmi-stats
+mkdir -p "$STATS_DIR"
+echo 0 > "$STATS_DIR/total"
+echo 0 > "$STATS_DIR/clean"
+echo 0 > "$STATS_DIR/infected"
+echo 0 > "$STATS_DIR/errors"
+
+# ── Minimal HTTP server ───────────────────────────────────────────────────────
+# Uses Node.js (already available from the base image)
+node - <<'EOF'
+'use strict';
+
+const http      = require('http');
+const fs        = require('fs');
+const os        = require('os');
+const path      = require('path');
+const { execSync, exec } = require('child_process');
+const { scanBuffer } = require('pompelmi');
+const { Verdict } = require('pompelmi');
+
+const PORT = 8080;
+const STATS = { total: 0, clean: 0, infected: 0, errors: 0, startedAt: new Date().toISOString() };
+
+function parseMultipart(req) {
+  return new Promise((resolve, reject) => {
+    const boundary = (req.headers['content-type'] || '').split('boundary=')[1];
+    if (!boundary) return reject(new Error('Missing multipart boundary'));
+
+    const chunks = [];
+    req.on('data', c => chunks.push(c));
+    req.on('error', reject);
+    req.on('end', () => {
+      const body   = Buffer.concat(chunks);
+      const delim  = Buffer.from('\r\n--' + boundary);
+      const parts  = [];
+      let start    = body.indexOf('--' + boundary);
+
+      while (start !== -1) {
+        const headerEnd = body.indexOf('\r\n\r\n', start);
+        if (headerEnd === -1) break;
+        const headerStr = body.slice(start, headerEnd).toString();
+        const nameMatch = headerStr.match(/name="([^"]+)"/);
+        const fileMatch = headerStr.match(/filename="([^"]+)"/);
+        const dataStart = headerEnd + 4;
+        const nextDelim = body.indexOf(delim, dataStart);
+        const dataEnd   = nextDelim === -1 ? body.indexOf('\r\n--' + boundary + '--', dataStart) : nextDelim;
+        if (dataEnd === -1) break;
+        parts.push({
+          name:     nameMatch  ? nameMatch[1]  : '',
+          filename: fileMatch  ? fileMatch[1]  : '',
+          data:     body.slice(dataStart, dataEnd),
+        });
+        start = body.indexOf('--' + boundary, dataEnd);
+        if (body.slice(start, start + boundary.length + 6).toString().includes('--\r\n')) break;
+      }
+      resolve(parts);
+    });
+  });
+}
+
+function isClamdRunning() {
+  try { execSync('clamdscan --no-summary /dev/null 2>/dev/null'); return true; }
+  catch { return false; }
+}
+
+const server = http.createServer(async (req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+
+  if (req.method === 'GET' && req.url === '/health') {
+    res.writeHead(200);
+    return res.end(JSON.stringify({ status: 'ok', clamd: isClamdRunning() ? 'running' : 'unavailable' }));
+  }
+
+  if (req.method === 'GET' && req.url === '/stats') {
+    res.writeHead(200);
+    return res.end(JSON.stringify({ ...STATS, uptime: process.uptime() }));
+  }
+
+  if (req.method === 'POST' && req.url === '/scan') {
+    try {
+      const parts = await parseMultipart(req);
+      const filePart = parts.find(p => p.filename);
+      if (!filePart) {
+        res.writeHead(400);
+        return res.end(JSON.stringify({ error: 'No file field in request' }));
+      }
+
+      STATS.total++;
+      const verdict = await scanBuffer(filePart.data);
+
+      let result;
+      if (verdict === Verdict.Clean) {
+        STATS.clean++;
+        result = { verdict: 'clean', file: filePart.filename, viruses: [] };
+      } else if (verdict === Verdict.Malicious) {
+        STATS.infected++;
+        result = { verdict: 'malicious', file: filePart.filename, viruses: [] };
+      } else {
+        STATS.errors++;
+        result = { verdict: 'error', file: filePart.filename, viruses: [] };
+      }
+
+      res.writeHead(200);
+      return res.end(JSON.stringify(result));
+    } catch (err) {
+      STATS.errors++;
+      res.writeHead(500);
+      return res.end(JSON.stringify({ error: err.message }));
+    }
+  }
+
+  res.writeHead(404);
+  res.end(JSON.stringify({ error: 'Not found' }));
+});
+
+server.listen(PORT, () => {
+  console.log(`[pompelmi] HTTP scan server listening on port ${PORT}`);
+  console.log(`[pompelmi] POST /scan   — scan a file`);
+  console.log(`[pompelmi] GET  /health — health check`);
+  console.log(`[pompelmi] GET  /stats  — scan statistics`);
+});
+
+process.on('SIGTERM', () => { server.close(); process.exit(0); });
+process.on('SIGINT',  () => { server.close(); process.exit(0); });
+EOF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.16.0",
+  "version": "1.18.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/packages/vscode/README.md

@@ -0,0 +1,61 @@
+# pompelmi — VS Code Extension
+
+Scan files for viruses directly from VS Code using pompelmi and ClamAV.
+
+## Requirements
+
+- [ClamAV](https://www.clamav.net/) installed (or clamd running via Docker)
+- Node.js and npm available in your PATH
+
+## Installation
+
+Install from the VS Code Marketplace:
+
+1. Open VS Code
+2. Press `Ctrl+P` (or `Cmd+P` on macOS)
+3. Run: `ext install pompelmi.pompelmi`
+
+## Usage
+
+### Scan a single file
+
+Right-click any file in the Explorer sidebar and select **"Scan with pompelmi"**.
+
+Results appear as VS Code notifications:
+
+- `✅ file.pdf — Clean`
+- `🚨 malware.exe — INFECTED (Win.Malware.Agent)`
+
+### Scan the workspace
+
+Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run:
+
+```
+pompelmi: Scan Workspace
+```
+
+### Configure
+
+Run `pompelmi: Configure` from the Command Palette to open settings.
+
+## Settings
+
+| Setting           | Default     | Description                              |
+|-------------------|-------------|------------------------------------------|
+| `pompelmi.host`   | `localhost` | clamd host                               |
+| `pompelmi.port`   | `3310`      | clamd port                               |
+| `pompelmi.socket` | *(empty)*   | clamd UNIX socket path (takes precedence over host/port) |
+
+## Using with Docker
+
+Start clamd via the official pompelmi Docker image:
+
+```bash
+docker run -p 3310:3310 -p 8080:8080 pompelmi/scanner
+```
+
+Then set `pompelmi.host` to `localhost` and `pompelmi.port` to `3310`.
+
+## License
+
+ISC © pompelmi contributors

package/packages/vscode/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "pompelmi",
+  "displayName": "pompelmi — Antivirus File Scanner",
+  "description": "Scan files for viruses directly from VS Code using pompelmi and ClamAV.",
+  "version": "0.1.0",
+  "publisher": "pompelmi",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pompelmi/pompelmi.git"
+  },
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": ["Other", "Linters"],
+  "keywords": ["antivirus", "clamav", "security", "malware", "virus"],
+  "icon": "icon.png",
+  "activationEvents": [
+    "onCommand:pompelmi.scanFile"
+  ],
+  "main": "./src/extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "pompelmi.scanFile",
+        "title": "Scan with pompelmi",
+        "category": "pompelmi"
+      },
+      {
+        "command": "pompelmi.scanWorkspace",
+        "title": "Scan Workspace",
+        "category": "pompelmi"
+      },
+      {
+        "command": "pompelmi.configure",
+        "title": "Configure pompelmi",
+        "category": "pompelmi"
+      }
+    ],
+    "menus": {
+      "explorer/context": [
+        {
+          "command": "pompelmi.scanFile",
+          "when": "resourceScheme == 'file'",
+          "group": "7_modification"
+        }
+      ]
+    },
+    "configuration": {
+      "title": "pompelmi",
+      "properties": {
+        "pompelmi.host": {
+          "type": "string",
+          "default": "localhost",
+          "description": "clamd host"
+        },
+        "pompelmi.port": {
+          "type": "number",
+          "default": 3310,
+          "description": "clamd port"
+        },
+        "pompelmi.socket": {
+          "type": "string",
+          "default": "",
+          "description": "clamd UNIX socket path (e.g. /run/clamav/clamd.sock)"
+        }
+      }
+    }
+  }
+}

package/packages/vscode/src/extension.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { execFile } = require('child_process');
+const path         = require('path');
+
+function getScanOptions(vscode) {
+  const cfg    = vscode.workspace.getConfiguration('pompelmi');
+  const host   = cfg.get('host', 'localhost');
+  const port   = cfg.get('port', 3310);
+  const socket = cfg.get('socket', '');
+  const args   = ['scan'];
+  if (socket) { args.push('--socket', socket); }
+  else        { args.push('--host', host, '--port', String(port)); }
+  args.push('--json');
+  return args;
+}
+
+function runScan(filePath, args, callback) {
+  const allArgs = [...args, filePath];
+  execFile('npx', ['pompelmi', ...allArgs], { timeout: 30000 }, (err, stdout) => {
+    if (err && !stdout) return callback(err, null);
+    try {
+      const result = JSON.parse(stdout);
+      callback(null, result);
+    } catch {
+      callback(new Error('Failed to parse pompelmi output'), null);
+    }
+  });
+}
+
+function activate(context) {
+  const vscode = require('vscode');
+
+  const scanFileCmd = vscode.commands.registerCommand('pompelmi.scanFile', async (uri) => {
+    const filePath = uri ? uri.fsPath : vscode.window.activeTextEditor?.document.uri.fsPath;
+    if (!filePath) {
+      vscode.window.showErrorMessage('pompelmi: No file selected.');
+      return;
+    }
+
+    const args = getScanOptions(vscode);
+    vscode.window.withProgress(
+      { location: vscode.ProgressLocation.Notification, title: `pompelmi: scanning ${path.basename(filePath)}...` },
+      () => new Promise(resolve => {
+        runScan(filePath, args, (err, result) => {
+          resolve();
+          if (err) {
+            vscode.window.showErrorMessage(`pompelmi error: ${err.message}`);
+            return;
+          }
+          const r = result?.results?.[0];
+          if (!r) {
+            vscode.window.showErrorMessage('pompelmi: unexpected response');
+            return;
+          }
+          if (r.verdict === 'clean') {
+            vscode.window.showInformationMessage(`✅ ${path.basename(filePath)} — Clean`);
+          } else if (r.verdict === 'infected') {
+            const virus = r.viruses?.[0] ? ` (${r.viruses[0]})` : '';
+            vscode.window.showErrorMessage(`🚨 ${path.basename(filePath)} — INFECTED${virus}`);
+          } else {
+            vscode.window.showWarningMessage(`⚠️ ${path.basename(filePath)} — Scan error`);
+          }
+        });
+      })
+    );
+  });
+
+  const scanWorkspaceCmd = vscode.commands.registerCommand('pompelmi.scanWorkspace', async () => {
+    const folders = vscode.workspace.workspaceFolders;
+    if (!folders || folders.length === 0) {
+      vscode.window.showErrorMessage('pompelmi: No workspace folder open.');
+      return;
+    }
+
+    const args = getScanOptions(vscode);
+    const dirPath = folders[0].uri.fsPath;
+
+    vscode.window.withProgress(
+      { location: vscode.ProgressLocation.Notification, title: 'pompelmi: scanning workspace...' },
+      () => new Promise(resolve => {
+        runScan(dirPath, args, (err, result) => {
+          resolve();
+          if (err) {
+            vscode.window.showErrorMessage(`pompelmi error: ${err.message}`);
+            return;
+          }
+          const infected = result?.infected ?? 0;
+          const scanned  = result?.scanned  ?? 0;
+          if (infected === 0) {
+            vscode.window.showInformationMessage(`✅ Workspace scan complete — ${scanned} files scanned, all clean.`);
+          } else {
+            vscode.window.showErrorMessage(`🚨 Workspace scan — ${infected} infected file(s) found out of ${scanned} scanned.`);
+          }
+        });
+      })
+    );
+  });
+
+  const configureCmd = vscode.commands.registerCommand('pompelmi.configure', () => {
+    vscode.commands.executeCommand('workbench.action.openSettings', 'pompelmi');
+  });
+
+  context.subscriptions.push(scanFileCmd, scanWorkspaceCmd, configureCmd);
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

package/src/Scorecard.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const CHECKS = [
+  {
+    key: 'scanEnabled',
+    check: 'Virus scanning enabled',
+    weight: 30,
+    pass: c => c.scanEnabled === true,
+    recommendation: 'Enable virus scanning by integrating pompelmi into your upload handler.',
+  },
+  {
+    key: 'mimeTypeAllowlist',
+    check: 'MIME type allowlist',
+    weight: 20,
+    pass: c => Array.isArray(c.mimeTypeAllowlist) && c.mimeTypeAllowlist.length > 0,
+    recommendation: 'Define an explicit MIME type allowlist to reject unexpected file types.',
+  },
+  {
+    key: 'fileSizeLimit',
+    check: 'File size limit',
+    weight: 10,
+    pass: c => typeof c.fileSizeLimit === 'number' && c.fileSizeLimit > 0,
+    recommendation: 'Set a maximum file size limit to prevent resource exhaustion.',
+  },
+  {
+    key: 'diskWriteBeforeScan',
+    check: 'No disk write before scan',
+    weight: 15,
+    pass: c => c.diskWriteBeforeScan === false,
+    recommendation: 'Scan files in-memory before writing to disk to avoid storing malware even temporarily.',
+  },
+  {
+    key: 'scanErrorBehavior',
+    check: 'Scan error behavior is reject',
+    weight: 10,
+    pass: c => c.scanErrorBehavior === 'reject',
+    recommendation: 'Set scanErrorBehavior to "reject" — failing open on scan errors is a security risk.',
+  },
+  {
+    key: 'clamdUnavailableBehavior',
+    check: 'clamd unavailable behavior is reject',
+    weight: 10,
+    pass: c => c.clamdUnavailableBehavior === 'reject',
+    recommendation: 'Set clamdUnavailableBehavior to "reject" — if clamd is down, deny uploads rather than allowing them through.',
+  },
+  {
+    key: 'tlsEnabled',
+    check: 'TLS enabled on upload endpoint',
+    weight: 5,
+    pass: c => c.tlsEnabled === true,
+    recommendation: 'Enable TLS (HTTPS) on your upload endpoint to protect files in transit.',
+  },
+];
+
+function scoreToGrade(score) {
+  if (score >= 90) return 'A';
+  if (score >= 75) return 'B';
+  if (score >= 60) return 'C';
+  if (score >= 45) return 'D';
+  return 'F';
+}
+
+async function generateScorecard(config = {}) {
+  const maxScore = CHECKS.reduce((s, c) => s + c.weight, 0);
+  let earned = 0;
+  const findings = [];
+  const recommendations = [];
+
+  for (const def of CHECKS) {
+    const passed = def.pass(config);
+    findings.push({ check: def.check, status: passed ? 'pass' : 'fail', weight: def.weight });
+    if (passed) {
+      earned += def.weight;
+    } else {
+      recommendations.push(def.recommendation);
+    }
+  }
+
+  const score = Math.round((earned / maxScore) * 100);
+  const grade = scoreToGrade(score);
+
+  return { grade, score, findings, recommendations };
+}
+
+module.exports = { generateScorecard };

package/src/Watcher.js

@@ -7,44 +7,79 @@ const { Verdict } = require('./verdicts.js');
 
 const DEBOUNCE_MS = 300;
 
+function quarantineFile(filePath, quarantineDir, virus) {
+  try {
+    fs.mkdirSync(quarantineDir, { recursive: true });
+    const basename    = path.basename(filePath);
+    const destBase    = path.join(quarantineDir, basename + '.quarantined');
+    const destJson    = destBase + '.json';
+    const sha256      = (() => { try { return require('crypto').createHash('sha256').update(fs.readFileSync(filePath)).digest('hex'); } catch { return ''; } })();
+
+    fs.renameSync(filePath, destBase);
+
+    const sidecar = {
+      originalPath: filePath,
+      virus: virus || '',
+      timestamp: new Date().toISOString(),
+      sha256,
+    };
+    fs.writeFileSync(destJson, JSON.stringify(sidecar, null, 2));
+
+    return destBase;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Watch a directory for new/modified files and scan each one automatically.
  * Uses fs.watch (no dependencies) with a 300 ms debounce.
  *
  * @param {string} dirPath
- * @param {object} [options] - Passed to scan() (host, port, socket, timeout, retries, retryDelay)
+ * @param {object} [options] - Passed to scan() (host, port, socket, timeout, retries, retryDelay).
+ *   Also accepts `quarantine` (string path) to enable auto-quarantine of infected files.
  * @param {{ onClean?: Function, onMalicious?: Function, onError?: Function }} [callbacks]
  * @returns {import('fs').FSWatcher}
  */
 function watch(dirPath, options = {}, { onClean, onMalicious, onError } = {}) {
-    const timers = new Map();
+  const { quarantine: quarantineDir, ...scanOptions } = options;
+  const timers = new Map();
+
+  if (quarantineDir) {
+    fs.mkdirSync(quarantineDir, { recursive: true });
+  }
 
-    return fs.watch(dirPath, { recursive: true }, (_eventType, filename) => {
-        if (!filename) return;
+  return fs.watch(dirPath, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
 
-        const fullPath = path.join(dirPath, filename);
+    const fullPath = path.join(dirPath, filename);
 
-        if (timers.has(fullPath)) clearTimeout(timers.get(fullPath));
+    if (timers.has(fullPath)) clearTimeout(timers.get(fullPath));
 
-        timers.set(fullPath, setTimeout(async () => {
-            timers.delete(fullPath);
+    timers.set(fullPath, setTimeout(async () => {
+      timers.delete(fullPath);
 
-            if (!fs.existsSync(fullPath)) return;
+      if (!fs.existsSync(fullPath)) return;
 
-            let stat;
-            try { stat = fs.statSync(fullPath); } catch { return; }
-            if (!stat.isFile()) return;
+      let stat;
+      try { stat = fs.statSync(fullPath); } catch { return; }
+      if (!stat.isFile()) return;
 
-            try {
-                const verdict = await scan(fullPath, options);
-                if (verdict === Verdict.Clean)          onClean     && onClean(fullPath);
-                else if (verdict === Verdict.Malicious) onMalicious && onMalicious(fullPath);
-                else                                    onError     && onError(new Error(`ScanError for ${fullPath}`), fullPath);
-            } catch (err) {
-                onError && onError(err, fullPath);
-            }
-        }, DEBOUNCE_MS));
-    });
+      try {
+        const verdict = await scan(fullPath, scanOptions);
+        if (verdict === Verdict.Clean) {
+          onClean && onClean(fullPath);
+        } else if (verdict === Verdict.Malicious) {
+          if (quarantineDir) quarantineFile(fullPath, quarantineDir, '');
+          onMalicious && onMalicious(fullPath);
+        } else {
+          onError && onError(new Error(`ScanError for ${fullPath}`), fullPath);
+        }
+      } catch (err) {
+        onError && onError(err, fullPath);
+      }
+    }, DEBOUNCE_MS));
+  });
 }
 
-module.exports = { watch };
+module.exports = { watch, quarantineFile };

package/src/index.js

@@ -8,5 +8,6 @@ const { notify }                                      = require('./WebhookNotifi
 const { createScanner }                               = require('./ScanEmitter.js');
 const { generateDashboard }                           = require('./Dashboard.js');
 const { generateShareCard }                           = require('./ShareCard.js');
+const { generateScorecard }                           = require('./Scorecard.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner, generateDashboard, generateShareCard };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner, generateDashboard, generateShareCard, generateScorecard };

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;

package/types/index.d.ts

@@ -142,14 +142,22 @@ export interface WatchCallbacks {
   onError?: (err: Error, filePath?: string) => void;
 }
 
+/** Options for watch() — extends ScanOptions with quarantine support */
+export interface WatchOptions extends ScanOptions {
+  /** Path to a quarantine directory. Infected files are moved here automatically. */
+  quarantine?: string;
+}
+
 /**
  * Watch a directory for new/modified files and scan each automatically.
  * Uses fs.watch with a 300 ms debounce. No dependencies.
+ * When `options.quarantine` is set, infected files are moved to that directory
+ * with a `.quarantined` extension and a sidecar JSON file.
  * Returns an FSWatcher; call .close() to stop watching.
  */
 export declare function watch(
   dirPath: string,
-  options?: ScanOptions,
+  options?: WatchOptions,
   callbacks?: WatchCallbacks
 ): FSWatcher;
 
@@ -266,3 +274,57 @@ export declare function generateShareCard(
   scanResults: ScanRow[] | DirectoryScanResult,
   options?: ShareCardOptions
 ): string;
+
+/** Input configuration for generateScorecard */
+export interface ScorecardConfig {
+  /** Whether virus scanning is enabled */
+  scanEnabled?: boolean;
+  /** Array of allowed MIME types (non-empty = pass) */
+  mimeTypeAllowlist?: string[];
+  /** Maximum file size in bytes (positive = pass) */
+  fileSizeLimit?: number;
+  /** Whether files are written to disk before scanning (false = pass) */
+  diskWriteBeforeScan?: boolean;
+  /** What to do on scan error: 'reject' = pass, anything else = fail */
+  scanErrorBehavior?: 'reject' | string;
+  /** What to do when clamd is unavailable: 'reject' = pass, anything else = fail */
+  clamdUnavailableBehavior?: 'reject' | string;
+  /** Whether TLS is enabled on the upload endpoint */
+  tlsEnabled?: boolean;
+}
+
+/** A single check result in a scorecard */
+export interface ScorecardFinding {
+  check: string;
+  status: 'pass' | 'fail';
+  weight: number;
+}
+
+/** Result returned by generateScorecard */
+export interface ScorecardResult {
+  /** Letter grade A–F */
+  grade: 'A' | 'B' | 'C' | 'D' | 'F';
+  /** Numeric score 0–100 */
+  score: number;
+  /** Per-check results */
+  findings: ScorecardFinding[];
+  /** Actionable recommendations for failed checks */
+  recommendations: string[];
+}
+
+/**
+ * Analyse a project's upload security configuration and return a grade A–F.
+ *
+ * @example
+ * const scorecard = await generateScorecard({
+ *   scanEnabled: true,
+ *   mimeTypeAllowlist: ['image/jpeg', 'image/png'],
+ *   fileSizeLimit: 10 * 1024 * 1024,
+ *   diskWriteBeforeScan: false,
+ *   scanErrorBehavior: 'reject',
+ *   clamdUnavailableBehavior: 'reject',
+ *   tlsEnabled: true,
+ * });
+ * console.log(scorecard.grade); // 'A'
+ */
+export declare function generateScorecard(config?: ScorecardConfig): Promise<ScorecardResult>;