@exortek/fastify-mongo-sanitize 1.2.0 → 1.2.1

package/FastifyMongoSanitizeError.js

@@ -0,0 +1,18 @@
+/**
+ * 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);
+  }
+}
+
+module.exports = FastifyMongoSanitizeError;

package/constants.js

@@ -0,0 +1,78 @@
+/**
+ * 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 `{ $... }`.
+]);
+
+/**
+ * Log levels for debugging
+ */
+const LOG_LEVELS = Object.freeze({
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  trace: 5,
+});
+
+/**
+ * Colors used for logging messages in the console
+ */
+const LOG_COLORS = Object.freeze({
+  error: '\x1b[31m', // Red
+  warn: '\x1b[33m', // Yellow
+  info: '\x1b[36m', // Cyan
+  debug: '\x1b[90m', // Gray
+  trace: '\x1b[35m', // Magenta
+  reset: '\x1b[0m', // Reset
+});
+
+/**
+ * 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.
+  removeMatches: false, // Remove the matched patterns. Default is false. If you want to remove the matched patterns instead of replacing them, you can set this option to true.
+  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. 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. 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.
+  },
+  debug: {
+    enabled: false,
+    level: 'info', // 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
+    logPatternMatches: false, // Log when patterns are matched
+    logSanitizedValues: false, // Log before/after values
+    logSkippedRoutes: false, // Log when routes are skipped
+  },
+});
+
+module.exports = {
+  PATTERNS,
+  LOG_LEVELS,
+  LOG_COLORS,
+  DEFAULT_OPTIONS,
+};

package/helpers.js

@@ -0,0 +1,172 @@
+const { LOG_LEVELS, LOG_COLORS } = require('./constants');
+const FastifyMongoSanitizeError = require('./FastifyMongoSanitizeError');
+
+/**
+ * Enhanced logging function with timing and context
+ * @param {Object} debugOpts - Debug options containing enabled status and log level
+ * @param {string} level - Log level (error, warn, info, debug, trace)
+ * @param {string} context - Context information (e.g., function name, operation)
+ * @param {string} message - Log message
+ * @param {*} data - Optional data to log
+ */
+const log = (debugOpts, level, context, message, data = null) => {
+  if (!debugOpts?.enabled || LOG_LEVELS[debugOpts.level || 'silent'] < LOG_LEVELS[level]) return;
+
+  const color = LOG_COLORS[level] || '';
+  const reset = LOG_COLORS.reset;
+  const timestamp = new Date().toISOString();
+
+  let logMessage = `${color}[mongo-sanitize:${level.toUpperCase()}]${reset} ${timestamp} [${context}] ${message}`;
+
+  if (data !== null) {
+    if (typeof data === 'object') {
+      console.log(logMessage);
+      console.log(`${color}Data:${reset}`, JSON.stringify(data, null, 2));
+    } else {
+      console.log(logMessage, data);
+    }
+  } else {
+    console.log(logMessage);
+  }
+};
+
+/**
+ * Performance timing utility
+ * @param {Object} debugOpts - Debug options
+ * @param {string} operation - Operation name
+ * @returns {Function} End timing function
+ */
+const startTiming = (debugOpts, operation) => {
+  const start = process.hrtime();
+  log(debugOpts, 'trace', 'TIMING', `Started: ${operation}`);
+
+  return () => {
+    const [seconds, nanoseconds] = process.hrtime(start);
+    const milliseconds = seconds * 1000 + nanoseconds / 1000000;
+    log(debugOpts, 'trace', 'TIMING', `Completed: ${operation} in ${milliseconds.toFixed(2)}ms`);
+  };
+};
+
+/**
+ * Checks if value is a valid email address
+ * @param {string} val - Value to check
+ * @returns {boolean} True if value is a valid email address
+ */
+const isEmail = (val) => /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/i.test(val);
+
+/**
+ * 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';
+
+/**
+ * Cleans a URL by removing leading and trailing slashes
+ * @param {string} url - URL to clean
+ * @returns {string|null} Cleaned URL or null if input is invalid
+ */
+const cleanUrl = (url) => {
+  if (typeof url !== 'string' || !url) return null;
+  const [path] = url.split(/[?#]/);
+  const trimmed = path.replace(/^\/+|\/+$/g, '');
+  return trimmed ? '/' + trimmed : null;
+};
+
+/**
+ * Validators for plugin options
+ * @constant {Object}
+ * @property {Function} replaceWith - Validates that replaceWith is a string
+ * @property {Function} removeMatches - Validates that removeMatches is a primitive (boolean or null)
+ * @property {Function} sanitizeObjects - Validates that sanitizeObjects is an array
+ * @property {Function} mode - Validates that mode is either 'auto' or 'manual'
+ * @property {Function} skipRoutes - Validates that skipRoutes is an array
+ * @property {Function} customSanitizer - Validates that customSanitizer is either null or a function
+ * @property {Function} recursive - Validates that recursive is a primitive (boolean or null)
+ * @property {Function} removeEmpty - Validates that removeEmpty is a primitive (boolean or null)
+ * @property {Function} patterns - Validates that patterns is an array
+ * @property {Function} allowedKeys - Validates that allowedKeys is either null or an array
+ * @property {Function} deniedKeys - Validates that deniedKeys is either null or an array
+ * @property {Function} stringOptions - Validates that stringOptions is a plain object
+ * @property {Function} arrayOptions - Validates that arrayOptions is a plain object
+ * @property {Function} debug - Validates that debug is a plain object with expected properties
+ * @returns {Object} Object containing validation functions for each option
+ */
+const validators = Object.freeze({
+  replaceWith: isString,
+  removeMatches: isPrimitive,
+  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,
+  debug: isPlainObject,
+});
+
+/**
+ * Validates plugin options
+ * @param {Object} options - Options to validate
+ * @throws {FastifyMongoSanitizeError} If any option is invalid
+ */
+const validateOptions = (options) => {
+  for (const [key, validate] of Object.entries(validators)) {
+    if (!validate(options[key])) {
+      throw new FastifyMongoSanitizeError(`Invalid configuration: ${key}`, 'type_error');
+    }
+  }
+};
+
+module.exports = {
+  log,
+  startTiming,
+  isEmail,
+  isString,
+  isPlainObject,
+  isArray,
+  isPrimitive,
+  isDate,
+  isFunction,
+  cleanUrl,
+  validateOptions,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exortek/fastify-mongo-sanitize",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "MongoDB query sanitizer for Fastify",
   "main": "index.js",
   "type": "commonjs",
@@ -54,6 +54,9 @@
   },
   "files": [
     "index.js",
-    "types/index.d.ts"
+    "types/index.d.ts",
+    "constants.js",
+    "helpers.js",
+    "FastifyMongoSanitizeError.js"
   ]
 }