Pompelmi

Local-first file upload scanning for Node.js.

Pompelmi inspects untrusted files before storage and helps you decide whether to allow, reject, or quarantine them before they reach downstream systems.

It is built for upload endpoints that cannot rely on filenames, extensions, or client-provided MIME types alone.

Install

npm install pompelmi

Requires Node.js 18+.

Quick Start

import { scanBytes } from 'pompelmi';

const report = await scanBytes(file.buffer, {
  ctx: {
    filename: file.originalname,
    mimeType: file.mimetype,
    size: file.size,
  },
});

if (!report.ok) {
  return res.status(422).json({
    error: 'Upload blocked',
    verdict: report.verdict,
    reasons: report.reasons,
  });
}

What Problem It Solves

Upload endpoints are part of your attack surface. A renamed executable, a risky PDF, or a hostile archive can look harmless until it is stored, unpacked, served, or parsed by another system.

Pompelmi adds checks at the upload boundary for:

• MIME spoofing and magic-byte mismatches
• Archive abuse such as ZIP bombs, traversal, and deep nesting
• Polyglot files and risky document structures
• Optional YARA-based signature matching

The goal is simple: inspect first, store later.

Why This Shape

• Plain Markdown, readable in GitHub and in a terminal
• Fast path first: install, example, then deeper links
• Minimal top-level detail, with docs and examples for everything else

Ecosystem

• pompelmi
• @pompelmi/express-middleware
• @pompelmi/koa-middleware
• @pompelmi/next-upload
• @pompelmi/nestjs-integration
• @pompelmi/fastify-plugin
• @pompelmi/ui-react
• @pompelmi/cli

Repository Layout

• src/ core library
• packages/ framework adapters and supporting packages
• examples/ runnable examples
• tests/ test coverage
• website/ documentation site

Development

pnpm install
pnpm test
pnpm build

Links

• Documentation
• Examples
• Contributing
• Security
• Roadmap

🌟 Featured In

Last updated: March 20, 2026

📋 Awesome Lists & Curated Collections

• Awesome JavaScript — sorrycc
• Awesome TypeScript — dzharii

📰 Newsletters & Roundups

• The Overflow Issue 319: Dogfooding your SDLC — Stack Overflow (2026-03-04)
• Hottest cybersecurity open-source tools of the month: February 2026 — Help Net Security (2026-02-26)
• Bytes #429 — Bytes (2025-10-03)
• Node Weekly Issue 594 — Node Weekly (2025-09-30)
• Det. Eng. Weekly Issue #124 - The DEFCON hangover is real — Detection Engineering (2025-08-13)

🔗 Other Mentions

• Defense against uploads: Q&A with OSS file scanner, pompelmi — Stack Overflow (2026-02-23)
• Pompelmi: Open-source secure file upload scanning for Node.js — Help Net Security (2026-02-02)

Found 9 mentions. To update, run npm run mentions:update.

License

MIT