@exortek/fastify-mongo-sanitize 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Memet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @exortek/fastify-mongo-sanitize
+
+A comprehensive Fastify plugin designed to protect your MongoDB queries from injection attacks by sanitizing request
+data. This plugin provides flexible sanitization options for request bodies, parameters, and query strings.
+
+### Compatibility
+
+| Plugin version | Fastify version |
+|----------------|:---------------:|
+| `^1.x`         |     `^4.x`      |
+| `^1.x`         |     `^5.x`      |
+
+### Key Features
+
+- Automatic sanitization of potentially dangerous MongoDB operators and special characters.
+- Multiple operation modes (auto, manual)
+- Customizable sanitization patterns and replacement strategies
+- Support for nested objects and arrays
+- Configurable string and array handling options
+- Skip routes functionality
+- Custom sanitizer support
+
+## Installation
+
+```bash
+npm install @exortek/fastify-mongo-sanitize
+```
+
+OR
+
+```bash
+yarn add @exortek/fastify-mongo-sanitize
+```
+
+## Usage
+
+Register the plugin with Fastify and specify the desired options.
+
+```javascript
+const fastify = require('fastify')({ logger: true });
+const fastifyMongoSanitize = require('@exortek/fastify-mongo-sanitize');
+
+fastify.register(fastifyMongoSanitize);
+
+fastify.listen(3000, (err, address) => {
+  if (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+  fastify.log.info(`Server listening on ${address}`);
+});
+```
+
+# Configuration Options
+
+The plugin accepts various configuration options to customize its behavior. Here's a detailed breakdown of all available
+options:
+
+## Core Options
+
+| Option            | Type           | Default                                            | Description                                                                                                                                                                                                                                                                               |
+|-------------------|----------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `replaceWith`     | string         | `''`                                               | The string to replace the matched patterns with. Default is an empty string. If you want to replace the matched patterns with a different string, you can set this option.                                                                                                                |
+| `sanitizeObjects` | array          | `['body', 'params', 'query']`                      | The request properties to sanitize. Default is `['body', 'params', 'query']`. You can specify any request property that you want to sanitize. It must be an object.                                                                                                                       |
+| `mode`            | string         | `'auto'`                                           | The mode of operation. Default is 'auto'. You can set this option to 'auto', 'manual'. If you set it to 'auto', the plugin will automatically sanitize the request objects. If you set it to 'manual', you can sanitize the request objects manually using the request.sanitize() method. |
+| `skipRoutes`      | array          | `[]`                                               | An array of routes to skip. Default is an empty array. If you want to skip certain routes from sanitization, you can specify the routes here. The routes must be in the format `/path`. For example, `['/health', '/metrics']`.                                                           |
+| `customSanitizer` | function\|null | `null`                                             | A custom sanitizer function. Default is null. If you want to use a custom sanitizer function, you can specify it here. The function must accept two arguments: the original data and the options object. It must return the sanitized data.                                               |
+| `recursive`       | boolean        | `true`                                             | Enable recursive sanitization. Default is true. If you want to recursively sanitize the nested objects, you can set this option to true.                                                                                                                                                  |
+| `removeEmpty`     | boolean        | `false`                                            | Remove empty values. Default is false. If you want to remove empty values after sanitization, you can set this option to true.                                                                                                                                                            |
+| `patterns`        | array          | `PATTERNS`                                         | An array of patterns to match. Default is an array of patterns that match illegal characters and sequences. You can specify your own patterns if you want to match different characters or sequences. Each pattern must be a regular expression.                                          |
+| `allowedKeys`     | array\|null    | `null`                                             | An array of allowed keys. Default is null. If you want to allow only certain keys in the object, you can specify the keys here. The keys must be strings. If a key is not in the allowedKeys array, it will be removed.                                                                   |
+| `deniedKeys`      | array\|null    | `null`                                             | An array of denied keys. Default is null. If you want to deny certain keys in the object, you can specify the keys here. The keys must be strings. If a key is in the deniedKeys array, it will be removed.                                                                               |
+| `stringOptions`   | object         | `{ trim: false,lowercase: false,maxLength: null }` | An object that controls string sanitization behavior. Default is an empty object. You can specify the following options: `trim`, `lowercase`, `maxLength`.                                                                                                                                |
+| `arrayOptions`    | object         | `{ filterNull: false, distinct: false}`            | An object that controls array sanitization behavior. Default is an empty object. You can specify the following options: `filterNull`, `distinct`.                                                                                                                                         |    
+
+## String Options
+
+The `stringOptions` object controls string sanitization behavior:
+
+```javascript
+{
+  trim: false,      // Whether to trim whitespace from start/end
+  lowercase: false, // Whether to convert strings to lowercase
+  maxLength: null   // Maximum allowed string length (null for no limit)
+}
+```
+
+## Array Options
+
+The `arrayOptions` object controls array sanitization behavior:
+
+```javascript
+{
+  filterNull: false, // Whether to remove null/undefined values
+  distinct: false    // Whether to remove duplicate values
+}
+```
+
+## Example Configuration
+
+```javascript
+const fastify = require('fastify')();
+
+fastify.register(require('fastify-mongo-sanitize'), {
+  replaceWith: '_',
+  mode: 'manual',
+  skipRoutes: ['/health', '/metrics'],
+  recursive: true,
+  removeEmpty: true,
+  stringOptions: {
+    trim: true,
+    maxLength: 100
+  },
+  arrayOptions: {
+    filterNull: true,
+    distinct: true
+  }
+});
+```
+
+## Notes
+
+- All options are optional and will use their default values if not specified
+- Custom patterns must be valid RegExp objects
+- When using `allowedKeys` or `deniedKeys`, make sure to include all necessary keys for your application
+- The `customSanitizer` function should be thoroughly tested before use in production
+- String length limiting (`maxLength`) only applies to string values, not keys
+- Array options are applied after all other sanitization steps
+
+## License
+
+**[MIT](https://github.com/ExorTek/fastify-mongo-sanitize/blob/master/LICENSE)**<br>
+
+Copyright © 2024 ExorTek

package/index.js

@@ -0,0 +1,283 @@
+'use strict';
+
+const fp = require('fastify-plugin');
+
+/**
+ * Collection of regular expression patterns used for sanitization
+ * @constant {RegExp[]}
+ */
+const PATTERNS = Object.freeze([
+  /[\$]/g, // Finds all '$' (dollar) characters in the text.
+  /\./g, // Finds all '.' (dot) characters in the text.
+  /[\\\/{}.(*+?|[\]^)]/g, // Finds special characters (\, /, {, }, (, ., *, +, ?, |, [, ], ^, )) that need to be escaped.
+  /[\u0000-\u001F\u007F-\u009F]/g, // Finds ASCII control characters (0x00-0x1F and 0x7F-0x9F range).
+  /\{\s*\$|\$?\{(.|\r?\n)*\}/g, // Finds placeholders or variables in the format `${...}` or `{ $... }`.
+]);
+
+/**
+ * Default configuration options for the plugin
+ * @constant {Object}
+ */
+const DEFAULT_OPTIONS = Object.freeze({
+  replaceWith: '', // The string to replace the matched patterns with. Default is an empty string. If you want to replace the matched patterns with a different string, you can set this option.
+  sanitizeObjects: ['body', 'params', 'query'], // The request properties to sanitize. Default is ['body', 'params', 'query']. You can specify any request property that you want to sanitize. It must be an object.
+  mode: 'auto', // The mode of operation. Default is 'auto'. You can set this option to 'auto', 'manual'. If you set it to 'auto', the plugin will automatically sanitize the request objects. If you set it to 'manual', you can sanitize the request objects manually using the request.sanitize() method.
+  skipRoutes: [], // An array of routes to skip. Default is an empty array. If you want to skip certain routes from sanitization, you can specify the routes here. The routes must be in the format '/path'. For example, ['/health', '/metrics'].
+  customSanitizer: null, // A custom sanitizer function. Default is null. If you want to use a custom sanitizer function, you can specify it here. The function must accept two arguments: the original data and the options object. It must return the sanitized data.
+  recursive: true, // Enable recursive sanitization. Default is true. If you want to recursively sanitize the nested objects, you can set this option to true.
+  removeEmpty: false, // Remove empty values. Default is false. If you want to remove empty values after sanitization, you can set this option to true.
+  patterns: PATTERNS, // An array of patterns to match. Default is an array of patterns that match illegal characters and sequences. You can specify your own patterns if you want to match different characters or sequences. Each pattern must be a regular expression.
+  allowedKeys: null, // An array of allowed keys. Default is null. If you want to allow only certain keys in the object, you can specify the keys here. The keys must be strings. If a key is not in the allowedKeys array, it will be removed.
+  deniedKeys: null, // An array of denied keys. Default is null. If you want to deny certain keys in the object, you can specify the keys here. The keys must be strings. If a key is in the deniedKeys array, it will be removed.
+  stringOptions: {
+    // String sanitization options.
+    trim: false, // Trim whitespace. Default is false. If you want to trim leading and trailing whitespace from the string, you can set this option to true.
+    lowercase: false, // Convert to lowercase. Default is false. If you want to convert the string to lowercase, you can set this option to true.
+    maxLength: null, // Maximum length. Default is null. If you want to limit the maximum length of the string, you can set this option to a number. If the string length exceeds the maximum length, it will be truncated.
+  },
+  arrayOptions: {
+    // Array sanitization options.
+    filterNull: false, // Filter null values. Default is false. If you want to remove null values from the array, you can set this option to true.
+    distinct: false, // Remove duplicate values. Default is false. If you want to remove duplicate values from the array, you can set this option to true.
+  },
+});
+
+/**
+ * Checks if value is a string
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is string
+ */
+const isString = (value) => typeof value === 'string';
+
+/**
+ * Checks if value is a plain object
+ * @param {*} obj - Value to check
+ * @returns {boolean} True if value is plain object
+ */
+const isPlainObject = (obj) => !!obj && Object.prototype.toString.call(obj) === '[object Object]';
+
+/**
+ * Checks if value is an array
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is array
+ */
+const isArray = (value) => Array.isArray(value);
+
+/**
+ * Checks if value is a primitive (null, number, or boolean)
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is primitive
+ */
+const isPrimitive = (value) => value === null || ['number', 'boolean'].includes(typeof value);
+
+/**
+ * Checks if value is a Date object
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is Date
+ */
+const isDate = (value) => value instanceof Date;
+
+/**
+ * Checks if value is a function
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is function
+ */
+const isFunction = (value) => typeof value === 'function';
+
+/**
+ * Error class for FastifyMongoSanitize
+ */
+class FastifyMongoSanitizeError extends Error {
+  /**
+   * Creates a new FastifyMongoSanitizeError
+   * @param {string} message - Error message
+   * @param {string} [type='generic'] - Error type
+   */
+  constructor(message, type = 'generic') {
+    super(message);
+    this.name = 'FastifyMongoSanitizeError';
+    this.type = type;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Sanitizes a string value according to provided options
+ * @param {string} str - String to sanitize
+ * @param {Object} options - Sanitization options
+ * @param {boolean} isValue - Whether string is a value or key
+ * @returns {string} Sanitized string
+ */
+const sanitizeString = (str, options, isValue = false) => {
+  if (!isString(str)) return str;
+
+  const { replaceWith, patterns, stringOptions } = options;
+
+  let result = patterns.reduce((acc, pattern) => acc.replace(pattern, replaceWith), str);
+
+  if (stringOptions.trim) result = result.trim();
+  if (stringOptions.lowercase) result = result.toLowerCase();
+  if (stringOptions.maxLength && result.length > stringOptions.maxLength && isValue)
+    result = result.slice(0, stringOptions.maxLength);
+
+  return result;
+};
+
+/**
+ * Sanitizes an array according to provided options
+ * @param {Array} arr - Array to sanitize
+ * @param {Object} options - Sanitization options
+ * @returns {Array} Sanitized array
+ * @throws {FastifyMongoSanitizeError} If input is not an array
+ */
+const sanitizeArray = (arr, options) => {
+  if (!isArray(arr)) throw new FastifyMongoSanitizeError('Input must be an array', 'type_error');
+
+  const { arrayOptions } = options;
+  let result = arr.map((item) => sanitizeValue(item, options));
+
+  if (arrayOptions.filterNull) result = result.filter(Boolean);
+  if (arrayOptions.distinct) result = [...new Set(result)];
+
+  return result;
+};
+
+/**
+ * Sanitizes an object according to provided options
+ * @param {Object} obj - Object to sanitize
+ * @param {Object} options - Sanitization options
+ * @returns {Object} Sanitized object
+ * @throws {FastifyMongoSanitizeError} If input is not an object
+ */
+const sanitizeObject = (obj, options) => {
+  if (!isPlainObject(obj)) throw new FastifyMongoSanitizeError('Input must be an object', 'type_error');
+
+  const { removeEmpty, allowedKeys, deniedKeys } = options;
+
+  return Object.entries(obj).reduce((acc, [key, value]) => {
+    if (allowedKeys?.length && !allowedKeys.includes(key)) return acc;
+    if (deniedKeys?.length && deniedKeys.includes(key)) return acc;
+
+    const sanitizedKey = sanitizeString(key, options, false);
+    if (removeEmpty && !sanitizedKey) return acc;
+
+    const sanitizedValue = sanitizeValue(value, options, true);
+    if (removeEmpty && !sanitizedValue) return acc;
+
+    acc[sanitizedKey] = sanitizedValue;
+    return acc;
+  }, {});
+};
+
+/**
+ * Sanitizes a value according to its type and provided options
+ * @param {*} value - Value to sanitize
+ * @param {Object} options - Sanitization options
+ * @param {boolean} isValue - Whether value is a value or key
+ * @returns {*} Sanitized value
+ */
+const sanitizeValue = (value, options, isValue) => {
+  if (!value) return value;
+  if (isPrimitive(value)) return value;
+  if (isDate(value)) return value;
+  if (isPlainObject(value)) return sanitizeObject(value, options);
+  if (isArray(value)) return sanitizeArray(value, options);
+  if (isString(value)) return sanitizeString(value, options, isValue);
+  return value;
+};
+
+/**
+ * Validates plugin options
+ * @param {Object} options - Options to validate
+ * @throws {FastifyMongoSanitizeError} If any option is invalid
+ */
+const validateOptions = (options) => {
+  const validators = {
+    replaceWith: isString,
+    sanitizeObjects: isArray,
+    mode: (value) => ['auto', 'manual'].includes(value),
+    skipRoutes: isArray,
+    customSanitizer: (value) => value === null || isFunction(value),
+    recursive: isPrimitive,
+    removeEmpty: isPrimitive,
+    patterns: isArray,
+    allowedKeys: (value) => value === null || isArray(value),
+    deniedKeys: (value) => value === null || isArray(value),
+    stringOptions: isPlainObject,
+    arrayOptions: isPlainObject,
+  };
+
+  for (const [key, validate] of Object.entries(validators)) {
+    if (!validate(options[key])) {
+      throw new FastifyMongoSanitizeError(`Invalid configuration: ${key}`, 'type_error');
+    }
+  }
+};
+
+/**
+ * Checks if a value contains potentially malicious patterns
+ * @param {*} value - Value to check
+ * @param {RegExp[]} patterns - Patterns to check against
+ * @returns {boolean} True if injection attempt detected
+ */
+const hasInjection = (value, patterns) => {
+  if (isString(value)) return patterns.some((pattern) => pattern.test(value));
+  if (isArray(value)) return value.some((item) => hasInjection(item, patterns));
+  if (isPlainObject(value))
+    return Object.entries(value).some(([key, val]) => hasInjection(key, patterns) || hasInjection(val, patterns));
+
+  return false;
+};
+
+/**
+ * Handles request sanitization
+ * @param {Object} request - Fastify request object
+ * @param {Object} options - Sanitization options
+ */
+const handleRequest = (request, options) => {
+  const { sanitizeObjects, customSanitizer } = options;
+
+  for (const sanitizeObject1 of sanitizeObjects) {
+    if (request[sanitizeObject1]) {
+      const originalData = request[sanitizeObject1];
+      request[sanitizeObject1] = customSanitizer ? customSanitizer(originalData) : sanitizeValue(originalData, options);
+    }
+  }
+};
+
+/**
+ * Fastify plugin for MongoDB query sanitization
+ * @param {Object} fastify - Fastify instance
+ * @param {Object} options - Plugin options
+ * @param {Function} done - Callback to signal completion
+ */
+const fastifyMongoSanitize = (fastify, options, done) => {
+  const opt = { ...DEFAULT_OPTIONS, ...options };
+
+  validateOptions(opt);
+
+  const skipRoutes = new Set(opt.skipRoutes);
+
+  if (opt.mode === 'manual') {
+    fastify.decorateRequest('sanitize', function (options) {
+      handleRequest(this, { ...opt, ...options });
+    });
+  }
+
+  if (opt.mode === 'auto') {
+    fastify.addHook('preHandler', (request, reply, done) => {
+      if (skipRoutes.has(request.url)) return done();
+      handleRequest(request, opt);
+      done();
+    });
+  }
+
+  done();
+};
+
+module.exports = fp(fastifyMongoSanitize, {
+  name: 'fastify-mongo-sanitize',
+  fastify: '>=4.x.x',
+});
+module.exports.default = fastifyMongoSanitize;
+module.exports.fastifyMongoSanitize = fastifyMongoSanitize;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@exortek/fastify-mongo-sanitize",
+  "version": "1.0.0",
+  "description": "MongoDB query sanitizer for Fastify",
+  "main": "index.js",
+  "type": "commonjs",
+  "types": "types/index.d.ts",
+  "scripts": {
+    "format": "prettier --write \"**/*.{js,ts,json}\"",
+    "test:tsd": "tsd",
+    "test:node": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExorTek/fastify-mongo-sanitize.git"
+  },
+  "keywords": [
+    "fastify",
+    "mongodb",
+    "sanitize",
+    "mongoose",
+    "fastify-plugin",
+    "data-validation",
+    "input-sanitization",
+    "security",
+    "web-application",
+    "nodejs",
+    "typescript",
+    "middleware",
+    "api-security",
+    "query-sanitization",
+    "no-sql",
+    "fastify-middleware",
+    "mongodb-sanitizer"
+  ],
+  "author": "ExorTek - https://github.com/ExorTek",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ExorTek/fastify-mongo-sanitize/issues"
+  },
+  "homepage": "https://github.com/ExorTek/fastify-mongo-sanitize#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "yarn@4.5.1",
+  "devDependencies": {
+    "fastify": "npm:fastify@5.1.0",
+    "fastify4": "npm:fastify@4.28.1",
+    "prettier": "^3.3.3",
+    "tsd": "^0.31.2"
+  },
+  "dependencies": {
+    "fastify-plugin": "^5.0.1"
+  },
+  "files": [
+    "index.js",
+    "types/index.d.ts"
+  ]
+}

package/types/index.d.ts

@@ -0,0 +1,34 @@
+import type { FastifyPluginCallback } from 'fastify';
+
+export interface FastifyMongoSanitizeOptions {
+  replaceWith?: string;
+  sanitizeObjects?: ('body' | 'params' | 'query')[];
+  mode?: 'auto' | 'manual';
+  skipRoutes?: string[];
+  customSanitizer?: ((data: any) => any) | null;
+  recursive?: boolean;
+  removeEmpty?: boolean;
+  patterns?: RegExp[];
+  allowedKeys?: string[] | null;
+  deniedKeys?: string[] | null;
+  stringOptions?: {
+    trim?: boolean;
+    lowercase?: boolean;
+    maxLength?: number | null;
+  };
+  arrayOptions?: {
+    filterNull?: boolean;
+    distinct?: boolean;
+  };
+}
+
+declare class FastifyMongoSanitizeError extends Error {
+  constructor(message: string, type?: string);
+  name: string;
+  type: string;
+}
+
+declare const fastifyMongoSanitize: FastifyPluginCallback<FastifyMongoSanitizeOptions>;
+
+export default fastifyMongoSanitize;
+export { FastifyMongoSanitizeError, fastifyMongoSanitize };