@exortek/nosql-sanitize-core 2.0.0

package/README.md

@@ -0,0 +1,79 @@
+# @exortek/nosql-sanitize-core
+
+> [!IMPORTANT]
+> This is an internal core package for the `nosql-sanitize` monorepo. It is not intended for standalone public use.
+
+Core sanitization engine for NoSQL injection prevention. This package provides the high-performance logic used by framework-specific adapters.
+
+## 📦 Usage
+
+Most users should install the framework-specific package ([`express-mongo-sanitize`](../express) or [`fastify-mongo-sanitize`](../fastify)) instead. Use this package directly only if you're building a custom integration or need standalone sanitization.
+
+### Installation (Internal Only)
+
+```bash
+npm install @exortek/nosql-sanitize-core
+```
+
+## 🚀 API Reference
+
+### `sanitizeValue(value, options, isValue?, depth?)`
+
+The main entry point for sanitization. It intelligently dispatches to specialized sanitizers based on the data type.
+
+```js
+const { sanitizeValue, resolveOptions } = require('@exortek/nosql-sanitize-core');
+
+const opts = resolveOptions();
+sanitizeValue('$admin', opts, true);           // → 'admin'
+sanitizeValue({ $gt: 1 }, opts);               // → { gt: 1 }
+sanitizeValue(['$a', '$b'], opts);             // → ['a', 'b']
+```
+
+### `resolveOptions(options?)`
+
+Merges user-provided options with defaults, pre-compiles regex patterns, and validates the configuration.
+
+```js
+const { resolveOptions } = require('@exortek/nosql-sanitize-core');
+
+const opts = resolveOptions({
+  replaceWith: '_',
+  maxDepth: 5,
+});
+```
+
+### `handleRequest(request, options)`
+
+A utility function to sanitize a request object's fields (`body`, `query`, `params`) in-place. Used by Express and Fastify adapters.
+
+---
+
+## ⚙️ Configuration Options
+
+| Option | Type | Default | Description |
+|:-------|:-----|:--------|:------------|
+| `replaceWith` | `string` | `''` | String to replace matched patterns with. |
+| `removeMatches` | `boolean` | `false` | If `true`, removes the entire key-value pair if a match is found. |
+| `sanitizeObjects` | `string[]` | `['body', 'query']` | Fields on the request object to sanitize. |
+| `contentTypes` | `string[] \| null` | `[...]` | Only sanitize `body` for these content types. `null` = all. |
+| `mode` | `'auto' \| 'manual'` | `'auto'` | Automatically sanitize or expose `req.sanitize()`. |
+| `skipRoutes` | `(string \| RegExp)[]` | `[]` | Routes to ignore during auto-sanitization. |
+| `maxDepth` | `number \| null` | `null` | Maximum recursion depth for nested structures. |
+| `recursive` | `boolean` | `true` | Whether to recursively sanitize nested objects/arrays. |
+| `onSanitize` | `function` | `null` | Hook called when a value is sanitized. |
+| `allowedKeys` | `string[]` | `[]` | Whitelist of keys to allow without sanitization. |
+| `deniedKeys` | `string[]` | `[]` | Blacklist of keys to completely remove. |
+
+## 🔍 Default Patterns
+
+The core engine targets common MongoDB injection vectors:
+
+1.  **Operator Prefix**: `$` (Matches characters used for `$gt`, `$ne`, `$where`, etc.)
+2.  **Control Characters**: Null bytes and C0/C1 control characters (`\u0000-\u001F`).
+
+You can override these by passing a `patterns` array in the options.
+
+## 📜 License
+
+[MIT](../../LICENSE) — Created by **ExorTek**

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@exortek/nosql-sanitize-core",
+  "version": "2.0.0",
+  "description": "Core sanitization engine for NoSQL injection prevention",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "types": "./types/index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExorTek/nosql-sanitize.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/ExorTek/nosql-sanitize/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/ExorTek/nosql-sanitize/issues"
+  },
+  "keywords": [
+    "nosql",
+    "sanitize",
+    "mongodb",
+    "injection",
+    "security",
+    "core",
+    "backend"
+  ],
+  "author": "ExorTek - https://github.com/ExorTek",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "types/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/constants.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const PATTERNS = Object.freeze([/\$/g, /[\u0000-\u001F\u007F-\u009F]/g]);
+
+const LOG_LEVELS = Object.freeze({
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  trace: 5,
+});
+
+const LOG_COLORS = Object.freeze({
+  error: '\x1b[31m',
+  warn: '\x1b[33m',
+  info: '\x1b[36m',
+  debug: '\x1b[90m',
+  trace: '\x1b[35m',
+  reset: '\x1b[0m',
+});
+
+const DEFAULT_OPTIONS = Object.freeze({
+  replaceWith: '',
+  removeMatches: false,
+  sanitizeObjects: ['body', 'query'],
+  contentTypes: ['application/json', 'application/x-www-form-urlencoded'],
+  mode: 'auto',
+  skipRoutes: [],
+  customSanitizer: null,
+  onSanitize: null,
+  recursive: true,
+  removeEmpty: false,
+  maxDepth: null,
+  patterns: PATTERNS,
+  allowedKeys: [],
+  deniedKeys: [],
+  stringOptions: {
+    trim: false,
+    lowercase: false,
+    maxLength: null,
+  },
+  arrayOptions: {
+    filterNull: false,
+    distinct: false,
+  },
+  debug: {
+    enabled: false,
+    level: 'info',
+    logPatternMatches: false,
+    logSanitizedValues: false,
+    logSkippedRoutes: false,
+  },
+});
+
+module.exports = { PATTERNS, LOG_LEVELS, LOG_COLORS, DEFAULT_OPTIONS };

package/src/errors.js

@@ -0,0 +1,18 @@
+'use strict';
+
+class NoSQLSanitizeError extends Error {
+  constructor(message, type = 'generic') {
+    super(message);
+    this.name = 'NoSQLSanitizeError';
+    this.type = type;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  code() {
+    return this.type;
+  }
+}
+
+module.exports = { NoSQLSanitizeError };

package/src/helpers.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const { LOG_LEVELS, LOG_COLORS } = require('./constants');
+const { NoSQLSanitizeError } = require('./errors');
+
+const isString = (value) => typeof value === 'string';
+const isArray = (value) => Array.isArray(value);
+const isBoolean = (value) => typeof value === 'boolean';
+const isNumber = (value) => typeof value === 'number';
+const isPrimitive = (value) => value === null || typeof value === 'boolean' || typeof value === 'number';
+const isDate = (value) => value instanceof Date;
+const isFunction = (value) => typeof value === 'function';
+
+const isPlainObject = (obj) => {
+  if (obj === null || typeof obj !== 'object' || isArray(obj) || obj instanceof Date || obj instanceof RegExp) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto === Object.prototype || proto === null) return true;
+  // Fastify query objects: proto is a null-prototype object (2 levels deep)
+  return Object.getPrototypeOf(proto) === null;
+};
+
+const isObjectEmpty = (obj) => {
+  if (!isPlainObject(obj)) return false;
+  for (const key in obj) {
+    if (Object.hasOwn(obj, key)) return false;
+  }
+  return true;
+};
+
+const EMAIL_RE = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/i;
+const isEmail = (val) => isString(val) && val.length > 5 && val.indexOf('@') > 0 && EMAIL_RE.test(val);
+
+const cleanUrl = (url) => {
+  if (!isString(url) || url.length === 0) return null;
+
+  // Strip query string and hash — indexOf faster than regex
+  let end = url.length;
+  const qIdx = url.indexOf('?');
+  const hIdx = url.indexOf('#');
+  if (qIdx !== -1 && qIdx < end) end = qIdx;
+  if (hIdx !== -1 && hIdx < end) end = hIdx;
+
+  // Trim leading/trailing slashes
+  let start = 0;
+  while (start < end && url.charCodeAt(start) === 47) start++;
+  while (end > start && url.charCodeAt(end - 1) === 47) end--;
+
+  if (start >= end) return null;
+  return '/' + url.slice(start, end);
+};
+
+/**
+ * Extracts the mime type from a content-type header value.
+ * "application/json; charset=utf-8" → "application/json"
+ */
+const extractMimeType = (contentType) => {
+  if (!isString(contentType)) return null;
+  const idx = contentType.indexOf(';');
+  const mime = (idx === -1 ? contentType : contentType.slice(0, idx)).trim().toLowerCase();
+  return mime || null;
+};
+
+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();
+  const logMessage = `${color}[nosql-sanitize:${level.toUpperCase()}]${reset} ${timestamp} [${context}] ${message}`;
+
+  if (data !== null && typeof data === 'object') {
+    console.log(logMessage);
+    console.log(`${color}Data:${reset}`, JSON.stringify(data, null, 2));
+  } else if (data !== null) {
+    console.log(logMessage, data);
+  } else {
+    console.log(logMessage);
+  }
+};
+
+const startTiming = (debugOpts, operation) => {
+  if (!debugOpts?.enabled) return () => {};
+  const start = process.hrtime();
+  log(debugOpts, 'trace', 'TIMING', `Started: ${operation}`);
+  return () => {
+    const [s, ns] = process.hrtime(start);
+    log(debugOpts, 'trace', 'TIMING', `Completed: ${operation} in ${(s * 1000 + ns / 1e6).toFixed(2)}ms`);
+  };
+};
+
+const validators = Object.freeze({
+  replaceWith: isString,
+  removeMatches: isBoolean,
+  sanitizeObjects: isArray,
+  mode: (v) => ['auto', 'manual'].includes(v),
+  skipRoutes: isArray,
+  contentTypes: (v) => v === null || isArray(v),
+  customSanitizer: (v) => v === null || isFunction(v),
+  onSanitize: (v) => v === null || isFunction(v),
+  recursive: isBoolean,
+  removeEmpty: isBoolean,
+  maxDepth: (v) => v === null || (isNumber(v) && v > 0),
+  patterns: isArray,
+  allowedKeys: (v) => v === null || isArray(v),
+  deniedKeys: (v) => v === null || isArray(v),
+  stringOptions: isPlainObject,
+  arrayOptions: isPlainObject,
+  debug: isPlainObject,
+});
+
+const validateOptions = (options) => {
+  for (const [key, validate] of Object.entries(validators)) {
+    if (options[key] !== undefined && !validate(options[key])) {
+      throw new NoSQLSanitizeError(`Invalid configuration: "${key}"`, 'type_error');
+    }
+  }
+};
+
+module.exports = {
+  isString,
+  isArray,
+  isPlainObject,
+  isBoolean,
+  isNumber,
+  isPrimitive,
+  isDate,
+  isFunction,
+  isObjectEmpty,
+  isEmail,
+  cleanUrl,
+  extractMimeType,
+  log,
+  startTiming,
+  validateOptions,
+};

package/src/index.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const { DEFAULT_OPTIONS, PATTERNS, LOG_LEVELS, LOG_COLORS } = require('./constants');
+const { NoSQLSanitizeError } = require('./errors');
+const { sanitizeString, sanitizeArray, sanitizeObject, sanitizeValue } = require('./sanitizers');
+const helpers = require('./helpers');
+
+/**
+ * Resolves and validates configuration options by merging user-provided options
+ * with default options and applying additional validations and transformations.
+ * This function ensures that nested configuration objects are properly validated,
+ * and prepares the resolved options for efficient runtime use.
+ *
+ * @param {Object} [userOptions={}] - The user-provided configuration options.
+ * @throws {NoSQLSanitizeError} Throws an error if the provided options or nested
+ * objects do not have the expected types.
+ * @returns {Object} The fully resolved and validated options object, ready for use.
+ */
+const resolveOptions = (userOptions = {}) => {
+  // Ensure the base options argument is a valid plain object to prevent prototype pollution or type errors
+  if (!helpers.isPlainObject(userOptions)) {
+    throw new NoSQLSanitizeError('Options must be an object', 'type_error');
+  }
+
+  // Validate nested object types before merge to avoid corrupting the configuration structure
+  if (userOptions.debug !== undefined && !helpers.isPlainObject(userOptions.debug)) {
+    throw new NoSQLSanitizeError('Invalid configuration: "debug"', 'type_error');
+  }
+  if (userOptions.stringOptions !== undefined && !helpers.isPlainObject(userOptions.stringOptions)) {
+    throw new NoSQLSanitizeError('Invalid configuration: "stringOptions"', 'type_error');
+  }
+  if (userOptions.arrayOptions !== undefined && !helpers.isPlainObject(userOptions.arrayOptions)) {
+    throw new NoSQLSanitizeError('Invalid configuration: "arrayOptions"', 'type_error');
+  }
+
+  // Deep merge default options with user-provided options safely
+  const opts = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    stringOptions: { ...DEFAULT_OPTIONS.stringOptions, ...(userOptions.stringOptions || {}) },
+    arrayOptions: { ...DEFAULT_OPTIONS.arrayOptions, ...(userOptions.arrayOptions || {}) },
+    debug: { ...DEFAULT_OPTIONS.debug, ...(userOptions.debug || {}) },
+  };
+
+  helpers.validateOptions(opts);
+
+  // Pre-compile combined pattern (just once) for performance optimization during runtime
+  const patterns = opts.patterns || PATTERNS;
+  opts._combinedPattern = new RegExp(patterns.map((p) => p.source).join('|'), 'g');
+
+  // Parse skipRoutes: Separate exact string matches (converted to a Set for O(1) lookup)
+  // and RegExp patterns (kept in an array) for faster evaluation later
+  const rawSkipRoutes = userOptions.skipRoutes || [];
+  const exactSkipRoutes = new Set();
+  const regexSkipRoutes = [];
+
+  for (const route of rawSkipRoutes) {
+    if (route instanceof RegExp) {
+      regexSkipRoutes.push(route);
+    } else if (helpers.isString(route)) {
+      const cleaned = helpers.cleanUrl(route);
+      if (cleaned) exactSkipRoutes.add(cleaned);
+    }
+  }
+
+  opts.skipRoutes = { exact: exactSkipRoutes, regex: regexSkipRoutes };
+
+  // Normalize contentTypes to a Set of lowercase strings for case-insensitive O(1) lookups.
+  // A null value indicates that content-type checking should be bypassed entirely.
+  const rawContentTypes =
+    userOptions.contentTypes !== undefined ? userOptions.contentTypes : DEFAULT_OPTIONS.contentTypes;
+  opts.contentTypes = rawContentTypes === null ? null : new Set(rawContentTypes.map((ct) => ct.toLowerCase()));
+
+  // Convert allowed and denied keys to Sets for faster inclusion checks
+  opts.allowedKeys = new Set(userOptions.allowedKeys || []);
+  opts.deniedKeys = new Set(userOptions.deniedKeys || []);
+
+  // Set max depth constraint for nested object parsing to prevent stack overflow/ReDoS attacks
+  opts.maxDepth = userOptions.maxDepth !== undefined ? userOptions.maxDepth : null;
+
+  // Assign the optional custom callback for post-sanitization hooks
+  opts.onSanitize = userOptions.onSanitize || null;
+
+  return opts;
+};
+
+/**
+ * Determines whether a specified property on an object is writable.
+ *
+ * This function checks if the property on the given object or its prototype chain
+ * has a descriptor indicating it is writable (either the `writable` attribute is true
+ * or a `set` accessor exists). If the property cannot be found in the chain, it defaults to true.
+ *
+ * @param {Object} obj - The object to inspect.
+ * @param {string} prop - The name of the property to check for writability.
+ * @returns {boolean} Returns `true` if the property is writable or defaults to
+ * writable when no descriptor is found; otherwise, `false`.
+ */
+const isWritable = (obj, prop) => {
+  let cur = obj;
+  // Traverse up the prototype chain to find the property descriptor
+  while (cur) {
+    const desc = Object.getOwnPropertyDescriptor(cur, prop);
+    // If the descriptor is found, check if it allows assignment (writable or has a setter)
+    if (desc) return !!desc.writable || !!desc.set;
+    cur = Object.getPrototypeOf(cur);
+  }
+  // Default to true if no descriptor restricts it in the entire prototype chain
+  return true;
+};
+
+/**
+ * Determines whether a request's content type should be sanitized.
+ *
+ * @param {Object} request - The request object, which contains headers and may include a `get` method to retrieve headers.
+ * @param {Array<string>} contentTypes - A set of allowed MIME types or null to sanitize all content types.
+ * @returns {boolean} - Returns true if the content type should be sanitized, otherwise false.
+ */
+const shouldSanitizeContentType = (request, contentTypes) => {
+  // If contentTypes is explicitly null, bypass the check and sanitize everything
+  if (contentTypes === null) return true;
+
+  // Safely extract the content-type header, supporting both standard Node.js req.headers
+  // and Express.js req.get() method
+  const header =
+    (request.headers && request.headers['content-type']) ||
+    (typeof request.get === 'function' && request.get('content-type')) ||
+    null;
+
+  // If there is no content-type header (e.g., simple GET requests), default to sanitizing
+  if (!header) return true;
+
+  // Extract the base MIME type (ignoring charsets/boundaries) and check against the allowed Set
+  const mime = helpers.extractMimeType(header);
+  return mime ? contentTypes.has(mime) : true;
+};
+
+/**
+ * Handles the sanitization of a request object based on the provided options.
+ *
+ * This function processes specified fields within the request (`sanitizeObjects`)
+ * and sanitizes their values using either a custom sanitizer or a default sanitizer.
+ * It conditionally skips sanitization for the `body` field if its content type
+ * is not included in the allowed list (`contentTypes`).
+ *
+ * @param {Object} request - The HTTP request object to be sanitized.
+ * @param {Object} options - Configuration options for the sanitization process.
+ * @param {Array.<string>} options.sanitizeObjects - List of request fields to be sanitized (e.g., `body`, `query`, `params`).
+ * @param {Function} [options.customSanitizer] - Optional custom function to handle the sanitization of field values.
+ * @param {boolean} [options.debug] - Flag to enable or disable debug logging.
+ * @param {Array.<string>} [options.contentTypes] - Allowed content types that determine whether the `body` field is sanitized.
+ */
+const handleRequest = (request, options) => {
+  const { sanitizeObjects, customSanitizer, debug, contentTypes } = options;
+  const endTiming = helpers.startTiming(debug, 'Request Sanitization');
+
+  helpers.log(debug, 'info', 'REQUEST', 'Sanitizing request');
+
+  // Determine early on if the 'body' payload should be processed based on its MIME type
+  const shouldSanitizeBody = shouldSanitizeContentType(request, contentTypes);
+
+  for (const field of sanitizeObjects) {
+    // Skip 'body' specifically if the content-type validation failed
+    if (field === 'body' && !shouldSanitizeBody) {
+      helpers.log(debug, 'debug', 'REQUEST', 'Skipping body — content-type not in allowed list');
+      continue;
+    }
+
+    const data = request[field];
+
+    // Skip processing if the payload field is undefined or null
+    if (data == null) continue;
+
+    // Avoid running expensive sanitization logic on completely empty objects
+    if (helpers.isPlainObject(data) && helpers.isObjectEmpty(data)) continue;
+
+    helpers.log(debug, 'debug', 'REQUEST', `Sanitizing '${field}'`);
+
+    // Create a shallow clone of the data to avoid mutating references unexpectedly
+    // before applying the sanitization logic
+    const original = Array.isArray(data) ? [...data] : helpers.isPlainObject(data) ? { ...data } : data;
+
+    // Route the data through a custom sanitizer if provided, otherwise use the internal one
+    const sanitized = customSanitizer ? customSanitizer(original, options) : sanitizeValue(original, options);
+
+    // Specific workaround for Express 5+: 'req.query' might be defined as non-writable via getter/setter.
+    // If it's writable, do a standard assignment. If not, forcefully redefine the property.
+    if (isWritable(request, field)) {
+      request[field] = sanitized;
+    } else {
+      Object.defineProperty(request, field, {
+        value: sanitized,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+    }
+  }
+
+  endTiming();
+};
+
+/**
+ * Determines whether a given route should be skipped based on exact matches or regex patterns.
+ *
+ * @param {string} requestPath - The request path to be evaluated.
+ * @param {Object} skipRoutes - An object containing route skipping criteria.
+ * @param {Set<string>} skipRoutes.exact - A set of exact route paths to skip.
+ * @param {RegExp[]} skipRoutes.regex - An array of regular expressions to test against the route path.
+ * @param {Object} [debug] - Optional debugging configuration.
+ * @param {boolean} [debug.logSkippedRoutes] - Flag indicating whether skipped routes should be logged.
+ * @returns {boolean} `true` if the route should be skipped, otherwise `false`.
+ */
+const shouldSkipRoute = (requestPath, skipRoutes, debug) => {
+  const { exact, regex } = skipRoutes;
+
+  // Quick return if there are no skip rules configured
+  if (!exact.size && !regex.length) return false;
+
+  const cleaned = helpers.cleanUrl(requestPath);
+
+  // Check the exact matches first (O(1) Set lookup) for better performance
+  if (cleaned && exact.has(cleaned)) {
+    if (debug?.logSkippedRoutes) {
+      helpers.log(debug, 'info', 'SKIP', `Route skipped (exact): ${requestPath}`);
+    }
+    return true;
+  }
+
+  // Fallback to iterating through RegExp patterns if no exact match is found
+  if (regex.length && cleaned) {
+    for (const pattern of regex) {
+      // Reset lastIndex to 0 to prevent issues with global (/g) regular expressions maintaining state
+      pattern.lastIndex = 0;
+      if (pattern.test(cleaned)) {
+        if (debug?.logSkippedRoutes) {
+          helpers.log(debug, 'info', 'SKIP', `Route skipped (regex ${pattern}): ${requestPath}`);
+        }
+        return true;
+      }
+    }
+  }
+
+  return false;
+};
+
+module.exports = {
+  resolveOptions,
+  handleRequest,
+  shouldSkipRoute,
+  shouldSanitizeContentType,
+  isWritable,
+
+  sanitizeString,
+  sanitizeArray,
+  sanitizeObject,
+  sanitizeValue,
+
+  ...helpers,
+
+  DEFAULT_OPTIONS,
+  PATTERNS,
+  LOG_LEVELS,
+  LOG_COLORS,
+  NoSQLSanitizeError,
+};

package/src/sanitizers.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const { isString, isArray, isPlainObject, isPrimitive, isDate, isEmail, log } = require('./helpers');
+const { NoSQLSanitizeError } = require('./errors');
+
+/**
+ * Sanitizes a string value.
+ */
+const sanitizeString = (str, options, isValue = false) => {
+  if (!isString(str) || isEmail(str)) return str;
+
+  const { replaceWith, stringOptions, debug, _combinedPattern } = options;
+  const original = str;
+
+  _combinedPattern.lastIndex = 0;
+  let result = str.replace(_combinedPattern, replaceWith);
+
+  if (stringOptions.trim) result = result.trim();
+  if (stringOptions.lowercase) result = result.toLowerCase();
+  if (stringOptions.maxLength && isValue) result = result.slice(0, stringOptions.maxLength);
+
+  if (debug?.enabled && original !== result) {
+    log(debug, 'debug', 'STRING', 'Sanitized', { original, result });
+  }
+
+  return result;
+};
+
+/**
+ * Sanitizes an array.
+ */
+const sanitizeArray = (arr, options, depth) => {
+  if (!isArray(arr)) {
+    throw new NoSQLSanitizeError('Input must be an array', 'type_error');
+  }
+
+  const { recursive, arrayOptions } = options;
+  const len = arr.length;
+  const result = new Array(len);
+
+  for (let i = 0; i < len; i++) {
+    const item = arr[i];
+    if (!recursive && (isPlainObject(item) || isArray(item))) {
+      result[i] = item;
+    } else {
+      result[i] = sanitizeValue(item, options, true, depth);
+    }
+  }
+
+  if (!arrayOptions.filterNull && !arrayOptions.distinct) return result;
+
+  let out = result;
+  if (arrayOptions.filterNull) out = out.filter(Boolean);
+  if (arrayOptions.distinct) out = [...new Set(out)];
+  return out;
+};
+
+/**
+ * Sanitizes an object. Uses for..of Object.keys() — no tuple allocation.
+ */
+const sanitizeObject = (obj, options, depth) => {
+  if (!isPlainObject(obj)) {
+    throw new NoSQLSanitizeError('Input must be an object', 'type_error');
+  }
+
+  const { removeEmpty, allowedKeys, deniedKeys, removeMatches, _combinedPattern, debug, recursive, onSanitize } =
+    options;
+
+  const acc = {};
+  const keys = Object.keys(obj);
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const val = obj[key];
+
+    // Denied key — email value korunur (BUG-03 fix)
+    if (deniedKeys.size && deniedKeys.has(key)) {
+      if (isEmail(val)) {
+        acc[sanitizeString(key, options)] = val;
+        continue;
+      }
+      log(debug, 'debug', 'OBJECT', `Key '${key}' denied`);
+      continue;
+    }
+
+    // Allowed key filtresi
+    if (allowedKeys.size && !allowedKeys.has(key)) {
+      log(debug, 'debug', 'OBJECT', `Key '${key}' not in allowedKeys`);
+      continue;
+    }
+
+    const sanitizedKey = sanitizeString(key, options);
+
+    // removeMatches — tek _combinedPattern.test()
+    if (removeMatches) {
+      _combinedPattern.lastIndex = 0;
+      if (_combinedPattern.test(key)) continue;
+    }
+
+    if (removeEmpty && !sanitizedKey) continue;
+
+    // removeMatches — value pattern match
+    if (removeMatches && isString(val)) {
+      _combinedPattern.lastIndex = 0;
+      if (_combinedPattern.test(val)) continue;
+    }
+
+    const sanitizedValue =
+      !recursive && (isPlainObject(val) || isArray(val)) ? val : sanitizeValue(val, options, true, depth);
+
+    if (removeEmpty && !sanitizedValue) continue;
+
+    // onSanitize callback
+    if (onSanitize && isString(val) && val !== sanitizedValue) {
+      onSanitize({ key, originalValue: val, sanitizedValue, path: key });
+    }
+
+    acc[sanitizedKey] = sanitizedValue;
+  }
+
+  return acc;
+};
+
+/**
+ * Main dispatch — routes to appropriate sanitizer by type.
+ * @param {*} value
+ * @param {Object} options
+ * @param {boolean} isValue - true if this is a value (not a key)
+ * @param {number} depth - current recursion depth
+ */
+const sanitizeValue = (value, options, isValue = false, depth = 0) => {
+  if (value == null || isPrimitive(value) || isDate(value)) return value;
+
+  // Strings are always sanitized regardless of depth
+  if (isString(value)) return sanitizeString(value, options, isValue);
+
+  // maxDepth guard — stop recursing into nested objects/arrays
+  if (options.maxDepth !== null && depth >= options.maxDepth) return value;
+
+  if (isArray(value)) return sanitizeArray(value, options, depth + 1);
+  if (isPlainObject(value)) return sanitizeObject(value, options, depth + 1);
+  return value;
+};
+
+module.exports = { sanitizeString, sanitizeArray, sanitizeObject, sanitizeValue };

package/types/index.d.ts

@@ -0,0 +1,255 @@
+/// <reference types="node" />
+
+type NoSQLSanitizeCore = typeof noSQLSanitizeCore;
+
+declare namespace noSQLSanitizeCore {
+  export interface StringOptions {
+    /** Trim leading/trailing whitespace. @default false */
+    trim?: boolean;
+    /** Convert to lowercase. @default false */
+    lowercase?: boolean;
+    /** Truncate strings exceeding this length. @default null */
+    maxLength?: number | null;
+  }
+
+  export interface ArrayOptions {
+    /** Remove falsy values from arrays. @default false */
+    filterNull?: boolean;
+    /** Remove duplicate values from arrays. @default false */
+    distinct?: boolean;
+  }
+
+  export interface DebugOptions {
+    /** Enable debug logging. @default false */
+    enabled?: boolean;
+    /** Log level threshold. @default 'info' */
+    level?: 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+    /** Log regex pattern matches. @default false */
+    logPatternMatches?: boolean;
+    /** Log sanitized values (before/after). @default false */
+    logSanitizedValues?: boolean;
+    /** Log when routes are skipped. @default false */
+    logSkippedRoutes?: boolean;
+  }
+
+  /**
+   * Event emitted by the `onSanitize` callback when a value is changed.
+   */
+  export interface SanitizeEvent {
+    /** The object key that was sanitized. */
+    key: string;
+    /** The original value before sanitization. */
+    originalValue: string;
+    /** The value after sanitization. */
+    sanitizedValue: string;
+    /** Path to the sanitized key (currently same as `key`). */
+    path: string;
+  }
+
+  /**
+   * User-facing options passed to `resolveOptions()`,
+   * Express middleware, or Fastify plugin.
+   */
+  export interface SanitizeOptions {
+    /** String to replace matched patterns with. @default '' */
+    replaceWith?: string;
+    /** Remove entire key-value pair if a pattern matches. @default false */
+    removeMatches?: boolean;
+    /** Request fields to sanitize. @default ['body', 'query'] */
+    sanitizeObjects?: string[];
+    /**
+     * Only sanitize request body for these content types.
+     * Set to `null` to sanitize all content types.
+     * Query/params are always sanitized regardless.
+     * @default ['application/json', 'application/x-www-form-urlencoded']
+     */
+    contentTypes?: string[] | null;
+    /** Sanitization mode. @default 'auto' */
+    mode?: 'auto' | 'manual';
+    /**
+     * Routes to skip. Supports exact strings (O(1) Set lookup)
+     * and RegExp patterns.
+     * @default []
+     */
+    skipRoutes?: (string | RegExp)[];
+    /** Custom sanitizer function. Overrides default sanitization. @default null */
+    customSanitizer?: ((data: any, options: ResolvedOptions) => any) | null;
+    /**
+     * Callback fired when a value is sanitized. Only fires when the value changes.
+     * @default null
+     */
+    onSanitize?: ((event: SanitizeEvent) => void) | null;
+    /** Recursively sanitize nested objects/arrays. @default true */
+    recursive?: boolean;
+    /** Remove falsy values after sanitization. @default false */
+    removeEmpty?: boolean;
+    /**
+     * Maximum recursion depth for nested objects.
+     * Strings are always sanitized regardless of depth.
+     * `null` = unlimited.
+     * @default null
+     */
+    maxDepth?: number | null;
+    /** Regex patterns to match and replace. @default [/\$/g, /control chars/g] */
+    patterns?: RegExp[];
+    /** Only allow these keys (empty = allow all). @default [] */
+    allowedKeys?: string[];
+    /** Remove these keys (empty = deny none). @default [] */
+    deniedKeys?: string[];
+    /** String transform options. */
+    stringOptions?: StringOptions;
+    /** Array transform options. */
+    arrayOptions?: ArrayOptions;
+    /** Debug logging configuration. */
+    debug?: DebugOptions;
+  }
+
+  /**
+   * Pre-compiled skip routes split into exact (Set) and regex (Array).
+   */
+  export interface ResolvedSkipRoutes {
+    exact: Set<string>;
+    regex: RegExp[];
+  }
+
+  /**
+   * Options after `resolveOptions()` processing.
+   * Patterns are compiled, Sets are built, defaults are merged.
+   */
+  export interface ResolvedOptions {
+    replaceWith: string;
+    removeMatches: boolean;
+    sanitizeObjects: string[];
+    contentTypes: Set<string> | null;
+    mode: 'auto' | 'manual';
+    skipRoutes: ResolvedSkipRoutes;
+    customSanitizer: ((data: any, options: ResolvedOptions) => any) | null;
+    onSanitize: ((event: SanitizeEvent) => void) | null;
+    recursive: boolean;
+    removeEmpty: boolean;
+    maxDepth: number | null;
+    patterns: RegExp[];
+    allowedKeys: Set<string>;
+    deniedKeys: Set<string>;
+    stringOptions: Required<StringOptions>;
+    arrayOptions: Required<ArrayOptions>;
+    debug: Required<DebugOptions>;
+    /** Pre-compiled combined regex from all patterns. */
+    _combinedPattern: RegExp;
+  }
+
+  /**
+   * Merge user options with defaults, pre-compile patterns,
+   * and validate configuration.
+   */
+  export function resolveOptions(options?: SanitizeOptions): ResolvedOptions;
+
+  /**
+   * Sanitize a request object's body, query, and/or params in-place.
+   * Respects content-type guards and Express 5 non-writable properties.
+   */
+  export function handleRequest(request: any, options: ResolvedOptions): void;
+
+  /**
+   * Check if a request path matches any skip route.
+   * Exact strings use O(1) Set lookup, regex patterns iterate.
+   */
+  export function shouldSkipRoute(requestPath: string, skipRoutes: ResolvedSkipRoutes, debug?: DebugOptions): boolean;
+
+  /**
+   * Check if the request's content-type is in the allowed set.
+   * Returns `true` if body should be sanitized.
+   */
+  export function shouldSanitizeContentType(request: any, contentTypes: Set<string> | null): boolean;
+
+  /**
+   * Check if a property is writable on an object or its prototype chain.
+   */
+  export function isWritable(obj: any, prop: string): boolean;
+
+  // ── Sanitizers ────────────────────────────────────────────
+
+  /**
+   * Main dispatch — routes to appropriate sanitizer by type.
+   * @param value    - Value to sanitize (string, object, array, or primitive).
+   * @param options  - Resolved options.
+   * @param isValue  - `true` if this is a value (not an object key).
+   * @param depth    - Current recursion depth.
+   */
+  export function sanitizeValue(value: any, options: ResolvedOptions, isValue?: boolean, depth?: number): any;
+
+  /**
+   * Sanitize a single string. Preserves email addresses.
+   */
+  export function sanitizeString(str: any, options: ResolvedOptions, isValue?: boolean): any;
+
+  /**
+   * Sanitize all keys and values of a plain object.
+   */
+  export function sanitizeObject(
+    obj: Record<string, any>,
+    options: ResolvedOptions,
+    depth?: number,
+  ): Record<string, any>;
+
+  /**
+   * Sanitize all elements of an array.
+   */
+  export function sanitizeArray(arr: any[], options: ResolvedOptions, depth?: number): any[];
+
+  export function isString(value: any): value is string;
+  export function isArray(value: any): value is any[];
+  export function isPlainObject(value: any): value is Record<string, any>;
+  export function isBoolean(value: any): value is boolean;
+  export function isNumber(value: any): value is number;
+  export function isPrimitive(value: any): boolean;
+  export function isDate(value: any): value is Date;
+  export function isFunction(value: any): value is Function;
+  export function isObjectEmpty(obj: any): boolean;
+  export function isEmail(value: any): boolean;
+
+  /**
+   * Normalize a URL path: strip query string, trailing slashes.
+   */
+  export function cleanUrl(url: any): string | null;
+
+  /**
+   * Extract MIME type from a Content-Type header.
+   * `"application/json; charset=utf-8"` → `"application/json"`
+   */
+  export function extractMimeType(contentType: any): string | null;
+
+  /** Log a message at the given level. */
+  export function log(debugOpts: DebugOptions, level: string, context: string, message: string, data?: any): void;
+
+  /** Start a timing measurement. Returns a function to end timing. */
+  export function startTiming(debugOpts: DebugOptions, operation: string): () => void;
+
+  /** Validate an options object, throw on invalid config. */
+  export function validateOptions(options: Record<string, any>): void;
+
+  /** Default sanitization patterns: `$` operator + control characters. */
+  export const PATTERNS: ReadonlyArray<RegExp>;
+  /** Default options before user overrides. */
+  export const DEFAULT_OPTIONS: Readonly<SanitizeOptions>;
+  /** Numeric log level mapping. */
+  export const LOG_LEVELS: Readonly<Record<string, number>>;
+  /** ANSI color codes for log levels. */
+  export const LOG_COLORS: Readonly<Record<string, string>>;
+
+  export class NoSQLSanitizeError extends Error {
+    name: 'NoSQLSanitizeError';
+    type: string;
+    constructor(message: string, type?: string);
+    code(): string;
+  }
+
+  export const noSQLSanitizeCore: NoSQLSanitizeCore;
+  export { noSQLSanitizeCore as default };
+}
+
+declare function noSQLSanitizeCore(
+  ...params: Parameters<NoSQLSanitizeCore['resolveOptions']>
+): ReturnType<NoSQLSanitizeCore['resolveOptions']>;
+
+export = noSQLSanitizeCore;