pompelmi 0.23.0 → 0.24.0

package/README.md

@@ -1,3 +1,26 @@
+<div align="center">
+
+<!-- Language Selector -->
+<p>
+  <strong>Read this in other languages:</strong><br/>
+  <a href="docs/i18n/README.it.md">🇮🇹 Italiano</a> •
+  <a href="docs/i18n/README.fr.md">🇫🇷 Français</a> •
+  <a href="docs/i18n/README.es.md">🇪🇸 Español</a> •
+  <a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •
+  <a href="docs/i18n/README.ja.md">🇯🇵 日本語</a> •
+  <a href="docs/i18n/README.zh-CN.md">🇨🇳 简体中文</a> •
+  <a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
+  <a href="docs/i18n/README.pt-BR.md">🇧🇷 Português</a> •
+  <a href="docs/i18n/README.ru.md">🇷🇺 Русский</a> •
+  <a href="docs/i18n/README.tr.md">🇹🇷 Türkçe</a>
+</p>
+
+> 💡 **Translation Note:** Help improve translations by opening a PR. The English README is the source of truth.
+
+</div>
+
+---
+
 <!-- HERO START -->
 
 <p align="center">
@@ -14,21 +37,33 @@
   <a href="https://bytes.dev/archives/429"><img alt="Featured in Bytes #429" src="https://img.shields.io/badge/featured-Bytes%20%23429-111111"></a>
   <a href="https://dev.to/sonotommy/secure-nodejs-file-uploads-in-minutes-with-pompelmi-3jfe"><img alt="Featured on DEV.to" src="https://img.shields.io/badge/featured-DEV.to-0A0A0A?logo=devdotto"></a>
   <br/>
+  <a href="https://github.com/sorrycc/awesome-javascript"><img alt="Mentioned in Awesome JavaScript" src="https://awesome.re/mentioned-badge.svg"></a>
+  <a href="https://github.com/dzharii/awesome-typescript"><img alt="Mentioned in Awesome TypeScript" src="https://awesome.re/mentioned-badge-flat.svg"></a>
+  <br/>
   
 </p>
 
 <h1 align="center">pompelmi</h1>
 
+<p align="center">
+  <strong>Fast, Private, and Powerful File Malware Scanning for Node.js</strong>
+</p>
 
+<p align="center">
+  ⚡ Zero-config setup • 🔒 Privacy-first • 🧩 Composable scanners • 📦 Deep ZIP inspection • 🎯 Framework adapters
+</p>
 
 <p align="center">
+  <strong>YARA</strong> integration • <strong>ZIP bomb</strong> protection • Drop-in middleware for <strong>Express</strong>, <strong>Koa</strong>, <strong>NestJS</strong>, <strong>Fastify</strong>, and <strong>Next.js</strong> • <strong>CLI</strong> for CI/CD
+</p>
 
-<strong>Fast file‑upload malware scanning for Node.js</strong> — optional <strong>YARA</strong> integration, ZIP deep‑inspection, and drop‑in adapters for <em>Express</em>, <em>Koa</em>, and <em>Next.js</em>. Private by design. Typed. Tiny.
+<p align="center">
+  <em>Scan files before they hit disk. Keep user data private. Ship with confidence.</em>
 </p>
 
 **Keywords:** file upload security · malware detection · YARA · Node.js middleware · Express · Koa · Next.js · ZIP bomb protection
 
-
+---
 
 <p align="center">
   <a href="https://www.npmjs.com/package/pompelmi"><img alt="npm version" src="https://img.shields.io/npm/v/pompelmi?label=version&color=0a7ea4&logo=npm"></a>
@@ -39,6 +74,13 @@
   <a href="https://snyk.io/test/github/pompelmi/pompelmi"><img alt="Known Vulnerabilities" src="https://snyk.io/test/github/pompelmi/pompelmi/badge.svg"></a>
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@pompelmi/cli"><img alt="CLI version" src="https://img.shields.io/npm/v/@pompelmi/cli?label=CLI&color=0a7ea4&logo=npm"></a>
+  <a href="https://www.npmjs.com/package/@pompelmi/nestjs-integration"><img alt="NestJS version" src="https://img.shields.io/npm/v/@pompelmi/nestjs-integration?label=NestJS&color=E0234E&logo=nestjs"></a>
+  <a href="https://www.npmjs.com/package/@pompelmi/express-middleware"><img alt="Express version" src="https://img.shields.io/npm/v/@pompelmi/express-middleware?label=Express&color=000000&logo=express"></a>
+  <a href="https://www.npmjs.com/package/@pompelmi/next-upload"><img alt="Next.js version" src="https://img.shields.io/npm/v/@pompelmi/next-upload?label=Next.js&color=000000&logo=nextdotjs"></a>
+</p>
+
 <p align="center">
   <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white">
   <img alt="types" src="https://img.shields.io/badge/types-TypeScript-3178C6?logo=typescript&logoColor=white">
@@ -108,9 +150,12 @@
   - [Express](#express)
   - [Koa](#koa)
   - [Next.js (App Router)](#nextjs-app-router)
-- [CLI Tool](#cli-tool)
+- [Adapters](#adapters)
+- [GitHub Action](#github-action)
 - [Configuration](#configuration)
+- [YARA Getting Started](#yara-getting-started)
 - [Security Notes](#security-notes)
+
 - [Testing & Development](#testing--development)
 - [FAQ](#faq)
 - [Contributing](#contributing)
@@ -118,6 +163,25 @@
 
 ---
 
+## 🌍 Translations
+
+pompelmi documentation is available in multiple languages to help developers worldwide:
+
+- 🇮🇹 **[Italiano (Italian)](docs/i18n/README.it.md)** — Documentazione completa in italiano
+- 🇫🇷 **[Français (French)](docs/i18n/README.fr.md)** — Documentation complète en français
+- 🇪🇸 **[Español (Spanish)](docs/i18n/README.es.md)** — Documentación completa en español
+- 🇩🇪 **[Deutsch (German)](docs/i18n/README.de.md)** — Vollständige Dokumentation auf Deutsch
+- 🇯🇵 **[日本語 (Japanese)](docs/i18n/README.ja.md)** — 日本語による完全なドキュメント
+- 🇨🇳 **[简体中文 (Simplified Chinese)](docs/i18n/README.zh-CN.md)** — 完整的简体中文文档
+- 🇰🇷 **[한국어 (Korean)](docs/i18n/README.ko.md)** — 완전한 한국어 문서
+- 🇧🇷 **[Português (Brasil)](docs/i18n/README.pt-BR.md)** — Documentação completa em português
+- 🇷🇺 **[Русский (Russian)](docs/i18n/README.ru.md)** — Полная документация на русском
+- 🇹🇷 **[Türkçe (Turkish)](docs/i18n/README.tr.md)** — Türkçe tam dokümantasyon
+
+**Help improve translations:** We welcome contributions to improve and maintain translations. The English README is the authoritative source. To contribute, please open a Pull Request with your improvements.
+
+---
+
 ## 🚀 Overview
 
 **pompelmi** scans untrusted file uploads **before** they hit disk. A tiny, TypeScript-first toolkit for Node.js with composable scanners, deep ZIP inspection, and optional signature engines.
@@ -130,7 +194,13 @@
 
 **📦 ZIP hardening** — traversal/bomb guards, polyglot & macro hints
 
-**🔌 Drop-in adapters** — Express, Koa, Fastify, Next.js
+**🔌 Drop-in adapters** — Express, Koa, Fastify, Next.js, **NestJS**
+
+**🌊 Stream-based scanning** — memory-efficient processing with configurable buffer limits
+
+**⚙️ CLI for CI/CD** — standalone command-line tool for scanning files and directories
+
+**🔍 Polyglot detection** — advanced magic bytes analysis and embedded script detection
 
 **📘 Typed & tiny** — modern TS, minimal surface, tree-shakeable
 
@@ -144,8 +214,16 @@
 
 **🔍 Built‑in scanners** — drop‑in **CommonHeuristicsScanner** (PDF risky actions, Office macros, PE header) and **Zip‑bomb Guard**; add your own or YARA via a tiny `{ scan(bytes) }` contract.
 
+**🔬 Polyglot & embedded script detection** — advanced magic bytes analysis detects mixed-format files and embedded scripts with **30+ file signatures**.
+
+**🌊 Memory-efficient streaming** — scan large files without loading them entirely into memory with automatic stream routing.
+
 **⚙️ Compose scanning** — run multiple scanners in parallel or sequentially with timeouts and short‑circuiting via `composeScanners()`.
 
+**🏗️ Framework integrations** — native modules for **NestJS**, Express, Koa, Next.js, and Fastify with first-class TypeScript support.
+
+**🔧 Production-ready CLI** — standalone tool for CI/CD pipelines with watch mode, multiple output formats (JSON, table, minimal).
+
 **☁️ Zero cloud** — scans run in‑process. Keep bytes private. Perfect for GDPR/HIPAA compliance.
 
 **👨‍💻 DX first** — TypeScript types, ESM/CJS builds, tiny API, adapters for popular web frameworks.
@@ -181,7 +259,6 @@
 \* You can run YARA alongside ClamAV, but it’s not built‑in.
 
 ---
-
 ## 💬 What Developers Say
 
 > "pompelmi made it incredibly easy to add malware scanning to our Express API. The TypeScript support is fantastic!"
@@ -233,10 +310,6 @@ Validate customer document uploads (ID verification, tax forms) without exposing
 
 Protect learning management systems from malicious file uploads while maintaining student privacy.
 
-### 📱 SaaS Applications
-
-Add secure file upload capabilities to your multi-tenant platform with per-tenant policy customization.
-
 ### 🏢 Enterprise Document Management
 
 Scan files at ingestion time for corporate file sharing platforms, wikis, and collaboration tools.
@@ -249,6 +322,13 @@ Validate user-generated content uploads (images, videos, documents) before proce
 
 ## 🔧 Installation
 
+**pompelmi** is a privacy-first Node.js library for local file scanning.
+
+**Requirements:**
+- Node.js 18+
+- Optional: ClamAV binaries (for signature-based scanning)
+- Optional: YARA libraries (for custom rules)
+
 <table>
 <tr>
 <td><b>npm</b></td>
@@ -268,7 +348,7 @@ Validate user-generated content uploads (images, videos, documents) before proce
 </tr>
 </table>
 
-### 📦 Optional Framework Adapters
+#### 📦 Optional Framework Adapters
 
 ```bash
 # Express
@@ -280,8 +360,14 @@ npm i @pompelmi/koa-middleware
 # Next.js
 npm i @pompelmi/next-upload
 
+# NestJS
+npm i @pompelmi/nestjs-integration
+
 # Fastify (alpha)
 npm i @pompelmi/fastify-plugin
+
+# Standalone CLI
+npm i -g @pompelmi/cli
 ```
 
 > **Note:** Core library works standalone. Install adapters only if using specific frameworks.
@@ -389,75 +475,66 @@ export const dynamic = 'force-dynamic';
 export const POST = createNextUploadHandler({ ...policy, scanner });
 ```
 
----
-
-## 🖥️ CLI Tool
-
-**pompelmi** includes a modern command-line interface for scanning files directly from your terminal. Perfect for CI/CD pipelines, security audits, and local development.
-
-### Installation
-
-```bash
-# Install globally
-npm install -g @pompelmi/cli
+### NestJS
 
-# Or use with npx
-npx @pompelmi/cli scan file.pdf
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { PompelmiModule } from '@pompelmi/nestjs-integration';
+import { CommonHeuristicsScanner } from 'pompelmi';
+
+@Module({
+  imports: [
+    PompelmiModule.forRoot({
+      includeExtensions: ['pdf', 'zip', 'png', 'jpg'],
+      allowedMimeTypes: ['application/pdf', 'application/zip', 'image/png', 'image/jpeg'],
+      maxFileSizeBytes: 10 * 1024 * 1024,
+      scanners: [CommonHeuristicsScanner],
+    }),
+  ],
+})
+export class AppModule {}
+
+// upload.controller.ts
+import { Controller, Post, UploadedFile, UseInterceptors } from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { PompelmiInterceptor, PompelmiResult } from '@pompelmi/nestjs-integration';
+
+@Controller('upload')
+export class UploadController {
+  @Post()
+  @UseInterceptors(FileInterceptor('file'), PompelmiInterceptor)
+  async uploadFile(@UploadedFile() file: Express.Multer.File & { pompelmi?: PompelmiResult }) {
+    return { 
+      success: true, 
+      verdict: file.pompelmi?.verdict 
+    };
+  }
+}
 ```
 
-### Features
+> See `packages/nestjs-integration/README.md` for full documentation.
 
-🎨 **Modern Terminal UI** — Emoji-rich interface with progress indicators  
-⚡ **Fast Scanning** — Parallel file processing with real-time feedback  
-📊 **Detailed Reports** — Human-readable scan summaries with timing  
-🎯 **Smart Detection** — Built-in heuristics for common threats  
-🛡️ **Safe Defaults** — ZIP bomb protection and file size limits  
-
-### Usage
+### CLI Usage
 
 ```bash
 # Scan a single file
-pompelmi scan document.pdf
+pompelmi scan file.pdf
 
-# Scan a directory with progress
-pompelmi scan-dir ./uploads
+# Scan directory recursively
+pompelmi scan ./uploads --recursive
 
 # Watch directory for changes
 pompelmi watch ./uploads
 
-# Get help
-pompelmi --help
-```
-
-### Example Output
-
-```
-🛡️ Pompelmi Security Scanner v0.23.0
-
-📁 Scanning: document.pdf
-🔍 Checking file safety...
-✅ File passed all security checks
+# JSON output for CI/CD
+pompelmi scan ./dist --output json --exit-on-suspicious
 
-📊 Scan Summary (0.1s)
-• Files scanned: 1
-• Clean: 1 ✅
-• Suspicious: 0 ⚠️
-• Malicious: 0 ❌
+# Full options
+pompelmi scan --help
 ```
 
-### CI/CD Integration
-
-Use the CLI in your build pipelines:
-
-```yaml
-# GitHub Actions
-- name: Security Scan
-  run: npx @pompelmi/cli scan-dir ./dist
-
-# GitLab CI
-script:
-  - npx @pompelmi/cli scan build.zip
-```
+> See `packages/cli/README.md` for comprehensive CLI documentation.
 
 ---
 
@@ -858,9 +935,7 @@ You should see an HTTP **422 Unprocessable Entity** (blocked by policy). Clean f
 
 ---
 
-[...]
-
-## 🔔 Releases & security
+##  Releases & security
 
 - **Changelog / releases:** see [GitHub Releases](https://github.com/pompelmi/pompelmi/releases).
 - **Security disclosures:** please use [GitHub Security Advisories](https://github.com/pompelmi/pompelmi/security/advisories). We’ll coordinate a fix before public disclosure.

package/dist/pompelmi.cjs

@@ -54,9 +54,10 @@ function createPresetScanner(preset, opts = {}) {
                 opts.decompilationDepth || 'basic';
         if (!opts.decompilationEngine || opts.decompilationEngine === 'binaryninja-hlil' || opts.decompilationEngine === 'both') {
             try {
-                // Dynamic import to avoid bundling issues
-                import('@pompelmi/engine-binaryninja').then(({ createBinaryNinjaScanner }) => {
-                    const binjaScanner = createBinaryNinjaScanner({
+                // Dynamic import to avoid bundling issues - using Function to bypass TypeScript type checking
+                const importModule = new Function('specifier', 'return import(specifier)');
+                importModule('@pompelmi/engine-binaryninja').then((mod) => {
+                    const binjaScanner = mod.createBinaryNinjaScanner({
                         timeout: opts.decompilationTimeout || opts.timeout || 30000,
                         depth,
                         pythonPath: opts.pythonPath,
@@ -73,9 +74,10 @@ function createPresetScanner(preset, opts = {}) {
         }
         if (!opts.decompilationEngine || opts.decompilationEngine === 'ghidra-pcode' || opts.decompilationEngine === 'both') {
             try {
-                // Dynamic import for Ghidra engine (when implemented)
-                import('@pompelmi/engine-ghidra').then(({ createGhidraScanner }) => {
-                    const ghidraScanner = createGhidraScanner({
+                // Dynamic import for Ghidra engine (when implemented) - using Function to bypass TypeScript type checking
+                const importModule = new Function('specifier', 'return import(specifier)');
+                importModule('@pompelmi/engine-ghidra').then((mod) => {
+                    const ghidraScanner = mod.createGhidraScanner({
                         timeout: opts.decompilationTimeout || opts.timeout || 30000,
                         depth,
                         ghidraPath: opts.ghidraPath,
@@ -2272,13 +2274,13 @@ class HipaaComplianceManager {
     constructor(config) {
         this.auditEvents = [];
         this.config = {
-            enabled: true,
             sanitizeErrors: true,
             sanitizeFilenames: true,
             encryptTempFiles: true,
             memoryProtection: true,
             requireSecureTransport: true,
-            ...config
+            ...config,
+            enabled: config.enabled !== undefined ? config.enabled : true
         };
         this.sessionId = this.generateSessionId();
     }