@exortek/express-mongo-sanitize

A comprehensive Express middleware designed to protect your No(n)SQL queries from injection attacks by sanitizing request data.
This middleware provides flexible sanitization options for request bodies and query strings, and an optional handler for route parameters.

Compatibility

| Middleware version | Express version | |--------------------|:---------------:| | ^1.x | ^4.x | | ^1.x | ^5.x |

Features

• Automatic sanitization of req.body and req.query by default
• Supports deep/nested objects, arrays, and string transformation
• Allows custom sanitizer logic, key allow/deny lists, skip routes, and more
• Route params (req.params) can be sanitized with an explicit helper (see below)

Installation

yarn add @exortek/express-mongo-sanitize
# or
npm install @exortek/express-mongo-sanitize

Usage

Basic usage

const express = require('express');
const expressMongoSanitize = require('@exortek/express-mongo-sanitize');

const app = express();
app.use(express.json());

// Body and query are sanitized automatically:
app.use(expressMongoSanitize());

app.post('/submit', (req, res) => {
  res.json(req.body);
});

Sanitizing Route Params (req.params)

By default, only body and query are sanitized.
If you want to sanitize route parameters (req.params),
use the exported paramSanitizeHandler with Express's app.param or router.param:

// Route parameter sanitization (recommended way):
app.param('username', expressMongoSanitize.paramSanitizeHandler());

// Example route:
app.get('/user/:username', (req, res) => {
  res.json({ username: req.params.username });
});

Note:

• You can attach this for any route param, e.g. 'id', 'slug', etc.
• This gives you full control and doesn't require the middleware to know your routes.

Options

| Option | Type | Default | Description | |-------------------|----------|-------------------------------------|---------------------------------------------------------------------| | replaceWith | string | '' | String to replace matched patterns | | removeMatches | boolean | false | Remove values matching patterns entirely | | sanitizeObjects | string[] | ['body', 'query'] | List of request objects to sanitize | | mode | string | 'auto' | 'auto' for automatic, 'manual' for explicit req.sanitize() call | | skipRoutes | string[] | [] | List of paths to skip (e.g. ['/health']) | | customSanitizer | function | null | Custom sanitizer function, overrides built-in sanitizer | | recursive | boolean | true | Recursively sanitize nested values | | removeEmpty | boolean | false | Remove empty values after sanitization | | patterns | RegExp[] | See source code | Patterns to match for sanitization | | allowedKeys | string[] | [] | Only allow these keys (all if empty) | | deniedKeys | string[] | [] | Remove these keys (none if empty) | | stringOptions | object | See below | String transform options (trim, lowercase, maxLength) | | arrayOptions | object | See below | Array handling options (filterNull, distinct) | | debug | object | { enabled: false, level: "info" } | Enables debug logging for middleware internals. |

stringOptions default:

{
  trim: false,
  lowercase: false,
  maxLength: null
}

arrayOptions default:

{
  filterNull: false,
  distinct: false
}

Manual Mode

If you set mode: 'manual', the middleware will not sanitize automatically.
Call req.sanitize() manually in your route:

app.use(expressMongoSanitize({ mode: 'manual' }));

app.post('/manual', (req, res) => {
  req.sanitize({ replaceWith: '_' }); // custom options are supported here
  res.json(req.body);
});

Skipping Routes

Skip certain routes by adding their paths to skipRoutes:

app.use(expressMongoSanitize({ skipRoutes: ['/skip', '/status'] }));

// These routes will NOT be sanitized

Custom Sanitizer

Use a completely custom sanitizer function:

app.use(expressMongoSanitize({
  customSanitizer: (data, options) => {
    // Your custom logic
    return data;
  }
}));

Route Parameter Sanitization

By default, only body and query are sanitized. If you want to sanitize route parameters (req.params),
use the helper function with app.param or router.param:

app.param('username', expressMongoSanitize.paramSanitizeHandler());

This ensures that, for example, /user/$admin will be returned as { username: 'admin' }
in your handler.

TypeScript

Type definitions are included.
You can use this plugin in both CommonJS and ESM projects.

Advanced Usage

Custom Sanitizer per Route

You can override sanitizer options or use a completely custom sanitizer per route:

app.post('/profile', (req, res, next) => {
  req.sanitize({
    customSanitizer: (data) => {
      // For example, redact all strings:
      if (typeof data === 'string') return '[REDACTED]';
      return data;
    }
  });
  res.json(req.body);
});

Debugging & Logging

You can enable debug logs to see the internal operation of the middleware.
Useful for troubleshooting or when tuning sanitization behavior.

app.use(
  expressMongoSanitize({
    debug: {
      enabled: true,         // Turn on debug logs
      level: 'debug',        // Log level: 'error' | 'warn' | 'info' | 'debug' | 'trace'
      logSkippedRoutes: true // (optional) Log when routes are skipped
    },
    // ...other options
  })
);

Logging Levels

| Level | Description | |---------|--------------------------------------| | error | Logs only errors | | warn | Logs warnings and errors | | info | Logs informational messages | | debug | Logs detailed debug information | | trace | Logs very detailed trace information |

Using with Router

const router = express.Router();
router.use(expressMongoSanitize());
// You can use paramSanitizeHandler on router params as well:
router.param('userId', expressMongoSanitize.paramSanitizeHandler());

Troubleshooting

Route parameters are not being sanitized

By default, only body and query are sanitized.
To sanitize route parameters, use:

app.param('username', expressMongoSanitize.paramSanitizeHandler());

Skipping specific routes doesn't work as expected

Make sure you use the exact path as in your route definition,
and that you apply the middleware before your routes.

My request is not being sanitized

• Ensure your route handler is after the middleware in the stack.
• If you are using mode: 'manual', you must call req.sanitize() yourself.

For more troubleshooting, open an issue at Github Issues

License

MIT

Copyright © 2025 ExorTek