@roboteby/parry 1.1.1 → 2.0.0

package/src/core/engine.js

@@ -10,6 +10,7 @@ const {
   RequestShapeGuard,
 } = require('../detectors');
 const { safeStringify } = require('../utils/normalize');
+const { collectRequestTargets } = require('../express/request-targets');
 const { severityForThreats } = require('./scoring');
 const {
   createThreatEvent,
@@ -71,10 +72,17 @@ async function analyzeRequest(requestData, context) {
     };
   }
 
-  const threats = [
-    ...scanApplicationLayerGuards(requestData, config),
-    ...scanTargets(requestData.targets || [], config),
-  ];
+  const shapeThreat = scanRequestShape(requestData, config);
+  const shapeExceeded = Boolean(shapeThreat);
+  const targets = shapeExceeded
+    ? []
+    : requestData.targets || collectRequestTargets(requestData, config);
+  const structuredThreats = shapeExceeded
+    ? [shapeThreat]
+    : scanStructuredGuards(requestData, config, targets);
+  const threats = deduplicateThreats(
+    shapeExceeded ? structuredThreats : [...structuredThreats, ...scanTargets(targets, config)]
+  );
 
   if (threats.length > 0) {
     if (config.rateLimit && rateLimiter) {
@@ -189,7 +197,13 @@ function createRequestEventContext(requestData, timestamp) {
 }
 
 function scanApplicationLayerGuards(requestData, config) {
-  const threats = [];
+  const shapeThreat = scanRequestShape(requestData, config);
+  if (shapeThreat) return [shapeThreat];
+  const targets = requestData.targets || collectRequestTargets(requestData, config);
+  return scanStructuredGuards(requestData, config, targets);
+}
+
+function scanRequestShape(requestData, config) {
   const surfaces = {
     query: requestData.query || {},
     params: requestData.params || {},
@@ -198,8 +212,18 @@ function scanApplicationLayerGuards(requestData, config) {
 
   if (config.requestShape?.enabled) {
     const hit = RequestShapeGuard.scan(surfaces, config.requestShape);
-    if (hit) return [hit];
+    if (hit) return hit;
   }
+  return null;
+}
+
+function scanStructuredGuards(requestData, config, targets) {
+  const threats = [];
+  const surfaces = {
+    query: requestData.query || {},
+    params: requestData.params || {},
+    body: requestData.body,
+  };
 
   if (config.hpp?.enabled) {
     const hit = HPPDetector.scan(surfaces.query, config.hpp);
@@ -211,8 +235,25 @@ function scanApplicationLayerGuards(requestData, config) {
     if (hit) threats.push(hit);
   }
 
+  if (config.nosql) {
+    for (const [surface, value] of Object.entries(surfaces)) {
+      const hit = NoSQLDetector.inspect(value, {
+        rootPath: surface,
+        allowedOperators: config.nosqlConfig?.allowedOperators,
+      });
+      if (hit) {
+        threats.push({
+          detector: 'NOSQL_INJECTION',
+          field: hit.path,
+          pattern: hit.pattern,
+          reason: 'NoSQL operator or expression detected',
+        });
+      }
+    }
+  }
+
   if (config.pathTraversal?.enabled) {
-    const hit = PathTraversalDetector.scan(requestData.targets || []);
+    const hit = PathTraversalDetector.scan(targets);
     if (hit) threats.push(hit);
   }
 
@@ -227,23 +268,42 @@ function scanTargets(targets, config) {
 
     if (config.sql) {
       const hit = SQLInjectionDetector.scan(str);
-      if (hit) threats.push({ detector: 'SQL_INJECTION', field: label, pattern: hit });
+      if (hit) {
+        threats.push({
+          detector: 'SQL_INJECTION',
+          field: label,
+          pattern: hit,
+          reason: 'SQL injection pattern detected',
+        });
+      }
     }
 
     if (config.xss) {
       const hit = XSSDetector.scan(str);
-      if (hit) threats.push({ detector: 'XSS', field: label, pattern: hit });
-    }
-
-    if (config.nosql) {
-      const hit = NoSQLDetector.scan(value);
-      if (hit) threats.push({ detector: 'NOSQL_INJECTION', field: label, pattern: hit });
+      if (hit) {
+        threats.push({
+          detector: 'XSS',
+          field: label,
+          pattern: hit,
+          reason: 'Cross-site scripting pattern detected',
+        });
+      }
     }
   }
 
   return threats;
 }
 
+function deduplicateThreats(threats) {
+  const seen = new Set();
+  return threats.filter((threat) => {
+    const key = [threat.detector, threat.field, threat.pattern, threat.reason].join('\u0000');
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
 function enrichThreats(threats) {
   return threats.map((threat) => ({
     ...threat,
@@ -261,4 +321,4 @@ function toResponseThreat(threat) {
   return responseThreat;
 }
 
-module.exports = { analyzeRequest, scanTargets, scanApplicationLayerGuards };
+module.exports = { analyzeRequest, scanTargets, scanApplicationLayerGuards, deduplicateThreats };

package/src/core/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const { RateLimiter } = require('./rateLimiter');
-const { ThreatLogger } = require('./logger');
+const { RateLimiter } = require('../rate-limit/limiter');
+const { ThreatLogger } = require('../logger/console-reporter');
 const { MemoryStore, RedisStore } = require('../stores');
 
 module.exports = { RateLimiter, ThreatLogger, MemoryStore, RedisStore };

package/src/core/scoring.js

@@ -12,7 +12,11 @@ const THREAT_SEVERITY = {
 
 function severityForThreats(threats) {
   if (!threats || threats.length === 0) return 'none';
-  return THREAT_SEVERITY[threats[0].detector] || 'medium';
+  const rank = { none: 0, low: 1, medium: 2, high: 3, critical: 4 };
+  return threats.reduce((highest, threat) => {
+    const severity = threat.severity || THREAT_SEVERITY[threat.detector] || 'medium';
+    return rank[severity] > rank[highest] ? severity : highest;
+  }, 'none');
 }
 
 module.exports = { severityForThreats };

package/src/detectors/nosql.js

@@ -8,46 +8,66 @@ const {
 
 const NoSQLDetector = {
   /** @param {*} value @returns {string|null} */
-  scan(value) {
-    if (value !== null && typeof value === 'object') return _scanObject(value);
-    if (typeof value === 'string') return _scanString(value);
+  scan(value, options = {}) {
+    return this.inspect(value, options)?.pattern || null;
+  },
+
+  inspect(value, options = {}) {
+    const rootPath = options.rootPath || 'value';
+    const allowedOperators = options.allowedOperators || {};
+    if (value !== null && typeof value === 'object') {
+      return _scanObject(value, rootPath, allowedOperators);
+    }
+    if (typeof value === 'string') return _scanString(value, rootPath, allowedOperators);
     return null;
   },
 };
 
-function _scanObject(obj, depth = 0) {
-  if (depth > 6) return null;
+function _scanObject(obj, path, allowedOperators, depth = 0, seen = new WeakSet()) {
+  if (depth > 8 || seen.has(obj)) return null;
+  seen.add(obj);
   for (const key of Object.keys(obj)) {
-    if (NOSQL_DANGEROUS_OPERATORS.has(key)) return `Operador perigoso: ${key}`;
-    if (NOSQL_SUSPICIOUS_OPERATORS.has(key)) return `Operador suspeito: ${key}`;
+    if (NOSQL_DANGEROUS_OPERATORS.has(key)) {
+      return { pattern: `Operador perigoso: ${key}`, path: `${path}.${key}` };
+    }
+    if (NOSQL_SUSPICIOUS_OPERATORS.has(key) && !isAllowed(path, key, allowedOperators)) {
+      return { pattern: `Operador suspeito: ${key}`, path: `${path}.${key}` };
+    }
     const val = obj[key];
+    const childPath = Array.isArray(obj) ? `${path}[${key}]` : `${path}.${key}`;
     if (val && typeof val === 'object') {
-      const nested = _scanObject(val, depth + 1);
+      const nested = _scanObject(val, childPath, allowedOperators, depth + 1, seen);
       if (nested) return nested;
     }
     if (typeof val === 'string') {
-      const hit = _scanString(val);
+      const hit = _scanString(val, childPath, allowedOperators);
       if (hit) return hit;
     }
   }
   return null;
 }
 
-function _scanString(value) {
+function _scanString(value, path, allowedOperators) {
   if (!value || value.trim() === '') return null;
   if (value.trim().startsWith('{') || value.trim().startsWith('[')) {
     try {
       const parsed = JSON.parse(value);
       if (parsed && typeof parsed === 'object') {
-        const hit = _scanObject(parsed);
+        const hit = _scanObject(parsed, path, allowedOperators);
         if (hit) return hit;
       }
-    } catch (_) {}
+    } catch (_) {
+      // Non-JSON strings are checked by the bounded patterns below.
+    }
   }
   for (const pattern of NOSQL_STRING_PATTERNS) {
-    if (pattern.test(value)) return pattern.toString();
+    if (pattern.test(value)) return { pattern: pattern.toString(), path };
   }
   return null;
 }
 
+function isAllowed(path, operator, allowedOperators) {
+  return Array.isArray(allowedOperators[path]) && allowedOperators[path].includes(operator);
+}
+
 module.exports = { NoSQLDetector };

package/src/detectors/path-traversal.js

@@ -60,7 +60,9 @@ function collectStrings(value, label, seen = new WeakSet()) {
     for (const [key, child] of Object.entries(value)) {
       strings.push(...collectStrings(child, `${label}.${key}`, seen));
     }
-  } catch (_) {}
+  } catch (_) {
+    // Ignore objects that cannot expose enumerable values.
+  }
 
   return strings;
 }

package/src/express/ip-resolver.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const ipaddr = require('ipaddr.js');
+const MAX_PROXY_HOPS = 20;
 
 function getClientIp(req, options = {}) {
   const headers = req.headers || {};
@@ -11,9 +12,22 @@ function getClientIp(req, options = {}) {
   if (!isTrustedProxy(directIp, options.trustedProxies || [])) return directIp;
 
   const forwarded = getHeader(headers, 'x-forwarded-for');
-  const firstForwarded = forwarded ? forwarded.split(',')[0].trim() : '';
+  if (forwarded) {
+    const rawHops = String(forwarded).split(',');
+    if (rawHops.length === 0 || rawHops.length > MAX_PROXY_HOPS) return directIp;
+    const hops = rawHops.map((hop) => parseIp(hop));
+    if (hops.some((hop) => !hop)) return directIp;
+
+    for (let index = hops.length - 1; index >= 0; index -= 1) {
+      const hop = hops[index].toString();
+      if (!isTrustedProxy(hop, options.trustedProxies || [])) return hop;
+    }
+
+    return hops[0]?.toString() || directIp;
+  }
+
   const realIp = getHeader(headers, 'x-real-ip');
-  return normalizeIp(firstForwarded || realIp || directIp);
+  return realIp && parseIp(realIp) ? normalizeIp(realIp) : directIp;
 }
 
 function resolveClientIP(req, options = {}) {

package/src/express/middleware.js

@@ -1,6 +1,12 @@
 'use strict';
 
+const crypto = require('node:crypto');
 const { DEFAULTS } = require('../../config/defaults');
+const {
+  normalizeHeadersConfig,
+  normalizeNoSQLConfig,
+  validateParryOptions,
+} = require('../../config/validate');
 const { analyzeRequest } = require('../core/engine');
 const { RateLimiter } = require('../rate-limit/limiter');
 const { ThreatLogger } = require('../logger/console-reporter');
@@ -16,14 +22,14 @@ const {
   observeAuthenticationResult,
 } = require('../brute-force');
 const { resolveClientIP } = require('./ip-resolver');
-const { collectRequestTargets } = require('./request-targets');
 const { setRateLimitHeaders, respond } = require('./response');
 
 /**
  * Detects SQL Injection, XSS and NoSQL Injection in real-time.
  * Applies intelligent Rate Limiting with automatic banning for suspicious behavior.
  *
- * @param {import('../../types/index').Parry_DDoSOptions} options
+ * @deprecated Use createParry() instead.
+ * @param {import('../../types/index').ParryOptions} options
  * @returns {import('express').RequestHandler}
  */
 function Parry_DDoS(options = {}) {
@@ -101,7 +107,6 @@ async function handleRequest(req, res, next, context) {
     query: req.query || {},
     params: req.params || {},
     body: req.body,
-    targets: collectRequestTargets(req, config.maxObjectDepth),
     requestId,
     userAgent: getHeader(req.headers || {}, 'user-agent'),
   };
@@ -175,6 +180,7 @@ async function handleRequest(req, res, next, context) {
 }
 
 function mergeConfig(options) {
+  validateParryOptions(options);
   const config = { ...DEFAULTS, ...options };
 
   for (const key of ['hpp', 'prototypePollution', 'pathTraversal', 'requestShape']) {
@@ -198,6 +204,9 @@ function mergeConfig(options) {
   config.storeFailureMode =
     options.storeFailureMode === 'fail-closed' ? 'fail-closed' : 'fail-open';
   config.policies = buildPolicies(options);
+  config.headers = normalizeHeadersConfig(options.headers);
+  config.nosqlConfig = normalizeNoSQLConfig(options.nosql);
+  config.nosql = config.nosqlConfig.enabled;
   config.bruteForce =
     options.bruteForce === false
       ? false
@@ -366,7 +375,7 @@ function resolveRequestId(req, res, config) {
 }
 
 function createRequestId() {
-  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+  return `req_${crypto.randomUUID()}`;
 }
 
 function getHeader(headers, name) {

package/src/express/request-targets.js

@@ -1,32 +1,42 @@
 'use strict';
 
-const { SENSITIVE_HEADERS } = require('../../constants/patterns');
-const { flattenObject } = require('../utils/flatten');
 const { normalizeTarget } = require('../utils/normalize');
 
-function collectRequestTargets(req, maxDepth) {
+function collectRequestTargets(req, options = {}) {
   const targets = [];
   const headers = req.headers || {};
+  const maxDepth = typeof options === 'number' ? options : (options.maxObjectDepth ?? 8);
+  const headersToScan =
+    typeof options === 'number' || !options.headers
+      ? ['user-agent', 'referer', 'x-forwarded-for', 'cookie']
+      : options.headers.scan;
+  const seen = new WeakSet();
 
   const add = (label, value) => {
-    if (value != null) targets.push(normalizeTarget({ label, value }));
+    if (value == null) return;
+    const type = typeof value;
+    if (type === 'string' || type === 'number' || type === 'boolean' || type === 'bigint') {
+      targets.push(normalizeTarget({ label, value }));
+    }
   };
 
-  if (req.query && typeof req.query === 'object') {
-    for (const [key, value] of Object.entries(req.query)) add(`query.${key}`, value);
-  }
+  const collect = (value, label, depth) => {
+    if (value == null || typeof value !== 'object') return add(label, value);
+    if (depth > maxDepth || seen.has(value)) return;
+    seen.add(value);
 
-  if (req.params && typeof req.params === 'object') {
-    for (const [key, value] of Object.entries(req.params)) add(`params.${key}`, value);
-  }
+    for (const [key, child] of Object.entries(value)) {
+      collect(child, Array.isArray(value) ? `${label}[${key}]` : `${label}.${key}`, depth + 1);
+    }
+  };
 
-  if (req.body && typeof req.body === 'object') {
-    add('body', req.body);
-    for (const target of flattenObject(req.body, 'body', maxDepth)) add(target.label, target.value);
-  }
+  collect(req.query || {}, 'query', 0);
+  collect(req.params || {}, 'params', 0);
+  collect(req.body, 'body', 0);
 
-  for (const header of SENSITIVE_HEADERS) {
-    if (headers[header]) add(`header.${header}`, headers[header]);
+  for (const header of headersToScan || []) {
+    const key = Object.keys(headers).find((name) => name.toLowerCase() === header);
+    if (key) collect(headers[key], `header.${header}`, 0);
   }
 
   return targets;

package/src/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { Parry_DDoS, createParry } = require('./middleware');
+const { Parry_DDoS, createParry } = require('./express/middleware');
 const { RateLimiter, ThreatLogger } = require('./core');
 const { MemoryStore, RedisStore } = require('./stores');
 const { EventBus, MemoryEventStore } = require('./events');

package/src/utils/decode.js

@@ -4,7 +4,9 @@ function decodeSqlValue(input) {
   let result = input;
   try {
     result = decodeURIComponent(result.replace(/\+/g, ' '));
-  } catch (_) {}
+  } catch (_) {
+    // Preserve malformed encodings for the detector's raw checks.
+  }
   return decodeHtmlEntities(result, { hex: false });
 }
 

package/src/utils/normalize.js

@@ -2,7 +2,9 @@
 
 function safeStringify(value) {
   if (typeof value === 'string') return value;
-  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return String(value);
+  }
   try {
     return JSON.stringify(value);
   } catch {

package/types/admin.d.ts

@@ -0,0 +1,26 @@
+export {
+  createParryAdminRouter,
+  AdminRouterOptions,
+  AdminAuthMode,
+  AdminAuthConfig,
+  AdminAuthStrategyConfig,
+  AdminCombinedAuthConfig,
+  ParryAdminContext,
+} from './index';
+import { Request, RequestHandler } from 'express';
+import { AdminAuthConfig, ParryAdminContext } from './index';
+
+export declare function resolveParryContext(parry: unknown): Record<string, unknown> | null;
+export declare function createAdminAuthMiddleware(
+  config: AdminAuthConfig,
+  context?: Record<string, unknown>
+): RequestHandler;
+export declare function authenticateAdminRequest(
+  req: Request,
+  config: AdminAuthConfig,
+  context?: Record<string, unknown>
+): Promise<{ ok: boolean; statusCode?: number; admin?: ParryAdminContext }>;
+export declare function requireAdminAuth(
+  options?: Record<string, unknown>,
+  context?: Record<string, unknown> | null
+): RequestHandler;

package/types/brute-force.d.ts

@@ -0,0 +1,44 @@
+import { PolicyConfig, ThreatEvent } from './index';
+
+export interface BuiltKey {
+  type: string;
+  value: string;
+  key: string;
+}
+
+export declare function createBruteForceContext(
+  context: Record<string, unknown>
+): Record<string, unknown>;
+export declare function attachParryRequestApi(req: object, context: Record<string, unknown>): void;
+export declare function checkBruteForceBlock(
+  context: Record<string, unknown>
+): Promise<Record<string, unknown>>;
+export declare function observeAuthenticationResult(context: Record<string, unknown>): void;
+export declare function finalizeAuthenticationResult(
+  context: Record<string, unknown>
+): Promise<unknown>;
+export declare function createBruteForceEvent(context: Record<string, unknown>): ThreatEvent;
+export declare function buildBruteForceKeys(
+  policy: PolicyConfig,
+  requestData: Record<string, unknown>
+): BuiltKey[];
+export declare function buildRouteRateLimitKey(
+  policy: PolicyConfig,
+  requestData: Record<string, unknown>
+): BuiltKey | null;
+export declare function buildKey(
+  policyName: string,
+  spec: string | ((requestData: Record<string, unknown>) => unknown),
+  requestData: Record<string, unknown>,
+  namespace: string
+): BuiltKey | null;
+export declare function resolveValue(
+  path: string,
+  requestData: Record<string, unknown>
+): string | null;
+export declare function createBlockedResponse(blocked: Record<string, unknown>): {
+  statusCode: number;
+  headers: { 'Retry-After': number };
+  body: { error: string; code: string; retryAfter: number };
+};
+export declare function retryAfterSeconds(blocked: Record<string, unknown>): number;

package/types/core.d.ts

@@ -0,0 +1 @@
+export { RateLimiter, ThreatLogger, MemoryStore, RedisStore } from './index';

package/types/detectors.d.ts

@@ -0,0 +1,9 @@
+export {
+  SQLInjectionDetector,
+  XSSDetector,
+  NoSQLDetector,
+  HPPDetector,
+  PrototypePollutionDetector,
+  PathTraversalDetector,
+  RequestShapeGuard,
+} from './index';

package/types/events.d.ts

@@ -0,0 +1,16 @@
+export { EventBus, MemoryEventStore } from './index';
+export { ThreatEvent, ThreatLogEntry, EventFilters, EventPage } from './index';
+import { ThreatEvent, ThreatLogEntry } from './index';
+
+export declare function createThreatEvent(
+  input?: Partial<ThreatEvent> | ThreatLogEntry
+): ThreatEvent;
+export declare function createStoreErrorEvent(
+  error: unknown,
+  context?: Record<string, unknown>
+): ThreatEvent;
+export declare function createHookErrorEvent(
+  error: unknown,
+  event?: Partial<ThreatEvent>
+): ThreatEvent;
+export declare function sanitizeEvent<T>(event: T): T;