@niksbanna/bot-detector 1.0.0

package/src/core/BotDetector.js

@@ -0,0 +1,284 @@
+/**
+ * @fileoverview Main BotDetector orchestrator class.
+ */
+
+import { Signal } from './Signal.js';
+import { ScoringEngine } from './ScoringEngine.js';
+import { VerdictEngine, Verdict } from './VerdictEngine.js';
+
+/**
+ * Main bot detection orchestrator.
+ * Manages signals, runs detection, and produces verdicts.
+ * 
+ * @example
+ * const detector = new BotDetector();
+ * const result = await detector.detect();
+ * console.log(result.verdict); // 'human', 'suspicious', or 'bot'
+ */
+class BotDetector {
+  /**
+   * Creates a new BotDetector instance.
+   * @param {Object} [options={}] - Configuration options
+   * @param {Array<Signal>} [options.signals=[]] - Initial signals to register
+   * @param {Object.<string, number>} [options.weightOverrides={}] - Override signal weights
+   * @param {number} [options.humanThreshold=20] - Score threshold for human verdict
+   * @param {number} [options.suspiciousThreshold=50] - Score threshold for suspicious verdict
+   * @param {Array<string>} [options.instantBotSignals=[]] - Signal IDs that instantly flag as bot
+   * @param {boolean} [options.includeDefaults=true] - Include built-in signal detectors
+   * @param {number} [options.detectionTimeout=5000] - Timeout for detection in ms
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this._signals = new Map();
+    this._scoringEngine = new ScoringEngine({
+      weightOverrides: options.weightOverrides,
+    });
+    this._verdictEngine = new VerdictEngine({
+      humanThreshold: options.humanThreshold,
+      suspiciousThreshold: options.suspiciousThreshold,
+      instantBotSignals: options.instantBotSignals,
+    });
+    this._lastDetection = null;
+    this._detectionTimeout = options.detectionTimeout || 5000;
+    this._isRunning = false;
+
+    // Register initial signals
+    if (options.signals) {
+      for (const signal of options.signals) {
+        this.registerSignal(signal);
+      }
+    }
+  }
+
+  /**
+   * Register a signal detector.
+   * @param {Signal} signal - Signal instance to register
+   * @returns {BotDetector} this instance for chaining
+   * @throws {Error} If signal with same ID already registered
+   */
+  registerSignal(signal) {
+    if (!(signal instanceof Signal)) {
+      throw new Error('Signal must be an instance of Signal class');
+    }
+    
+    const id = signal.id;
+    if (this._signals.has(id)) {
+      throw new Error(`Signal with ID "${id}" is already registered`);
+    }
+    
+    this._signals.set(id, signal);
+    return this;
+  }
+
+  /**
+   * Register multiple signals at once.
+   * @param {Array<Signal>} signals - Array of signal instances
+   * @returns {BotDetector} this instance for chaining
+   */
+  registerSignals(signals) {
+    for (const signal of signals) {
+      this.registerSignal(signal);
+    }
+    return this;
+  }
+
+  /**
+   * Unregister a signal by ID.
+   * @param {string} signalId - Signal ID to remove
+   * @returns {boolean} True if signal was removed
+   */
+  unregisterSignal(signalId) {
+    return this._signals.delete(signalId);
+  }
+
+  /**
+   * Get a registered signal by ID.
+   * @param {string} signalId - Signal ID
+   * @returns {Signal|undefined}
+   */
+  getSignal(signalId) {
+    return this._signals.get(signalId);
+  }
+
+  /**
+   * Get all registered signals.
+   * @returns {Array<Signal>}
+   */
+  getSignals() {
+    return Array.from(this._signals.values());
+  }
+
+  /**
+   * Get signals by category.
+   * @param {string} category - Category name
+   * @returns {Array<Signal>}
+   */
+  getSignalsByCategory(category) {
+    return this.getSignals().filter(s => s.category === category);
+  }
+
+  /**
+   * Run all signal detectors and calculate verdict.
+   * @param {Object} [options={}] - Detection options
+   * @param {boolean} [options.skipInteractionSignals=false] - Skip signals requiring interaction
+   * @returns {Promise<DetectionResult>}
+   */
+  async detect(options = {}) {
+    if (this._isRunning) {
+      throw new Error('Detection is already running');
+    }
+
+    this._isRunning = true;
+    this._scoringEngine.reset();
+
+    const startTime = performance.now();
+    const signalResults = new Map();
+    
+    try {
+      // Filter signals based on options
+      const signalsToRun = this.getSignals().filter(signal => {
+        if (options.skipInteractionSignals && signal.requiresInteraction) {
+          return false;
+        }
+        return true;
+      });
+
+      // Run all signals with timeout
+      const detectionPromises = signalsToRun.map(async signal => {
+        const result = await Promise.race([
+          signal.run(),
+          new Promise(resolve => 
+            setTimeout(() => resolve({ 
+              triggered: false, 
+              value: null, 
+              confidence: 0, 
+              error: 'timeout' 
+            }), this._detectionTimeout)
+          ),
+        ]);
+        
+        return { signal, result };
+      });
+
+      const results = await Promise.all(detectionPromises);
+
+      // Process results
+      for (const { signal, result } of results) {
+        signalResults.set(signal.id, {
+          ...result,
+          category: signal.category,
+          weight: signal.weight,
+          description: signal.description,
+        });
+
+        this._scoringEngine.addResult(signal.id, result, signal.weight);
+      }
+
+      // Calculate score and verdict
+      const score = this._scoringEngine.calculate();
+      const triggeredSignals = this._scoringEngine.getTriggeredSignals();
+      const verdict = this._verdictEngine.getVerdict(score, triggeredSignals);
+
+      const detectionTime = performance.now() - startTime;
+
+      this._lastDetection = {
+        ...verdict,
+        signals: Object.fromEntries(signalResults),
+        breakdown: this._scoringEngine.getBreakdown(),
+        timestamp: Date.now(),
+        detectionTimeMs: Math.round(detectionTime),
+        totalSignals: signalsToRun.length,
+        triggeredSignals,
+      };
+
+      return this._lastDetection;
+    } finally {
+      this._isRunning = false;
+    }
+  }
+
+  /**
+   * Get the last detection result.
+   * @returns {DetectionResult|null}
+   */
+  getLastDetection() {
+    return this._lastDetection;
+  }
+
+  /**
+   * Get the current score (from last detection).
+   * @returns {number}
+   */
+  getScore() {
+    return this._lastDetection?.score ?? 0;
+  }
+
+  /**
+   * Get triggered signals from last detection.
+   * @returns {Array<string>}
+   */
+  getTriggeredSignals() {
+    return this._lastDetection?.triggeredSignals ?? [];
+  }
+
+  /**
+   * Check if detection is currently running.
+   * @returns {boolean}
+   */
+  isRunning() {
+    return this._isRunning;
+  }
+
+  /**
+   * Reset the detector state.
+   */
+  reset() {
+    this._scoringEngine.reset();
+    this._lastDetection = null;
+    for (const signal of this._signals.values()) {
+      signal.reset();
+    }
+  }
+
+  /**
+   * Update configuration options.
+   * @param {Object} options - New options
+   */
+  configure(options) {
+    if (options.humanThreshold !== undefined || options.suspiciousThreshold !== undefined) {
+      this._verdictEngine.setThresholds({
+        human: options.humanThreshold,
+        suspicious: options.suspiciousThreshold,
+      });
+    }
+    if (options.detectionTimeout !== undefined) {
+      this._detectionTimeout = options.detectionTimeout;
+    }
+  }
+
+  /**
+   * Create a detector with default signals.
+   * @param {Object} [options={}] - Configuration options
+   * @returns {BotDetector}
+   */
+  static withDefaults(options = {}) {
+    // This will be populated with default signals in the main export
+    return new BotDetector(options);
+  }
+}
+
+/**
+ * @typedef {Object} DetectionResult
+ * @property {string} verdict - 'human', 'suspicious', or 'bot'
+ * @property {number} score - Calculated score (0-100)
+ * @property {string} confidence - Confidence level
+ * @property {string} reason - Reason for verdict
+ * @property {Object} signals - Map of signal ID to results
+ * @property {Array<Object>} breakdown - Score contribution breakdown
+ * @property {number} timestamp - Detection timestamp
+ * @property {number} detectionTimeMs - Time taken for detection
+ * @property {number} totalSignals - Total signals evaluated
+ * @property {Array<string>} triggeredSignals - IDs of triggered signals
+ */
+
+export { BotDetector, Verdict };

package/src/core/ScoringEngine.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Scoring engine that calculates bot probability from signals.
+ */
+
+/**
+ * Calculates a weighted score from signal results.
+ * Score represents the probability of the visitor being a bot.
+ */
+class ScoringEngine {
+  /**
+   * Creates a new ScoringEngine instance.
+   * @param {Object} [options={}] - Configuration options
+   * @param {Object.<string, number>} [options.weightOverrides={}] - Override weights by signal ID
+   * @param {number} [options.maxScore=100] - Maximum possible score
+   */
+  constructor(options = {}) {
+    this.weightOverrides = options.weightOverrides || {};
+    this.maxScore = options.maxScore || 100;
+    this._results = new Map();
+  }
+
+  /**
+   * Get the effective weight for a signal.
+   * @param {string} signalId - Signal identifier
+   * @param {number} defaultWeight - Default weight from signal definition
+   * @returns {number}
+   */
+  getWeight(signalId, defaultWeight) {
+    return this.weightOverrides[signalId] ?? defaultWeight;
+  }
+
+  /**
+   * Add a signal result to the scoring calculation.
+   * @param {string} signalId - Signal identifier
+   * @param {Object} result - Signal detection result
+   * @param {boolean} result.triggered - Whether signal was triggered
+   * @param {number} result.confidence - Confidence level (0-1)
+   * @param {number} weight - Signal weight (0.1-1.0)
+   */
+  addResult(signalId, result, weight) {
+    const effectiveWeight = this.getWeight(signalId, weight);
+    this._results.set(signalId, {
+      ...result,
+      weight: effectiveWeight,
+      contribution: result.triggered ? effectiveWeight * result.confidence : 0,
+    });
+  }
+
+  /**
+   * Calculate the final score from all added results.
+   * Formula: (sum of contributions / sum of weights) * maxScore
+   * 
+   * @returns {number} Score between 0 and maxScore
+   */
+  calculate() {
+    if (this._results.size === 0) {
+      return 0;
+    }
+
+    let totalWeight = 0;
+    let totalContribution = 0;
+
+    for (const [, data] of this._results) {
+      totalWeight += data.weight;
+      totalContribution += data.contribution;
+    }
+
+    if (totalWeight === 0) {
+      return 0;
+    }
+
+    const score = (totalContribution / totalWeight) * this.maxScore;
+    return Math.round(score * 100) / 100; // Round to 2 decimal places
+  }
+
+  /**
+   * Get detailed breakdown of score contributions.
+   * @returns {Array<Object>} Array of signal contributions
+   */
+  getBreakdown() {
+    const breakdown = [];
+    
+    for (const [signalId, data] of this._results) {
+      breakdown.push({
+        signalId,
+        triggered: data.triggered,
+        confidence: data.confidence,
+        weight: data.weight,
+        contribution: data.contribution,
+        percentOfScore: this.calculate() > 0 
+          ? (data.contribution / this.calculate() * 100).toFixed(1)
+          : '0.0',
+      });
+    }
+
+    // Sort by contribution (highest first)
+    return breakdown.sort((a, b) => b.contribution - a.contribution);
+  }
+
+  /**
+   * Get all triggered signals.
+   * @returns {Array<string>} Array of triggered signal IDs
+   */
+  getTriggeredSignals() {
+    const triggered = [];
+    for (const [signalId, data] of this._results) {
+      if (data.triggered) {
+        triggered.push(signalId);
+      }
+    }
+    return triggered;
+  }
+
+  /**
+   * Get the number of triggered signals.
+   * @returns {number}
+   */
+  getTriggeredCount() {
+    let count = 0;
+    for (const [, data] of this._results) {
+      if (data.triggered) count++;
+    }
+    return count;
+  }
+
+  /**
+   * Reset all stored results.
+   */
+  reset() {
+    this._results.clear();
+  }
+}
+
+export { ScoringEngine };

package/src/core/Signal.js

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview Base Signal class for bot detection signals.
+ * All signal detectors must extend this class.
+ */
+
+/**
+ * Base class for all signal detectors.
+ * Signals detect specific indicators of automated browser behavior.
+ * 
+ * @abstract
+ * @example
+ * class CustomSignal extends Signal {
+ *   static id = 'custom-signal';
+ *   static category = 'custom';
+ *   static weight = 0.5;
+ *   static description = 'Detects custom bot behavior';
+ *   
+ *   async detect() {
+ *     const isSuspicious = // ... detection logic
+ *     return {
+ *       triggered: isSuspicious,
+ *       value: someValue,
+ *       confidence: 0.8
+ *     };
+ *   }
+ * }
+ */
+class Signal {
+  /**
+   * Unique identifier for this signal.
+   * @type {string}
+   */
+  static id = 'base-signal';
+
+  /**
+   * Category this signal belongs to.
+   * Categories: 'environment', 'behavior', 'fingerprint', 'timing', 'automation'
+   * @type {string}
+   */
+  static category = 'uncategorized';
+
+  /**
+   * Weight of this signal in the scoring calculation.
+   * Range: 0.1 (low importance) to 1.0 (high importance)
+   * @type {number}
+   */
+  static weight = 0.5;
+
+  /**
+   * Human-readable description of what this signal detects.
+   * @type {string}
+   */
+  static description = 'Base signal class';
+
+  /**
+   * Whether this signal requires user interaction before it can detect.
+   * @type {boolean}
+   */
+  static requiresInteraction = false;
+
+  /**
+   * Creates a new Signal instance.
+   * @param {Object} [options={}] - Configuration options for this signal.
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this._lastResult = null;
+  }
+
+  /**
+   * Get the signal's unique identifier.
+   * @returns {string}
+   */
+  get id() {
+    return this.constructor.id;
+  }
+
+  /**
+   * Get the signal's category.
+   * @returns {string}
+   */
+  get category() {
+    return this.constructor.category;
+  }
+
+  /**
+   * Get the signal's weight.
+   * @returns {number}
+   */
+  get weight() {
+    return this.options.weight ?? this.constructor.weight;
+  }
+
+  /**
+   * Get the signal's description.
+   * @returns {string}
+   */
+  get description() {
+    return this.constructor.description;
+  }
+
+  /**
+   * Check if this signal requires interaction.
+   * @returns {boolean}
+   */
+  get requiresInteraction() {
+    return this.constructor.requiresInteraction;
+  }
+
+  /**
+   * Get the last detection result.
+   * @returns {SignalResult|null}
+   */
+  get lastResult() {
+    return this._lastResult;
+  }
+
+  /**
+   * Perform the detection check.
+   * Must be overridden by subclasses.
+   * 
+   * @abstract
+   * @returns {Promise<SignalResult>} Detection result
+   * @throws {Error} If not implemented by subclass
+   */
+  async detect() {
+    throw new Error(`Signal.detect() must be implemented by ${this.constructor.name}`);
+  }
+
+  /**
+   * Run detection and cache the result.
+   * @returns {Promise<SignalResult>}
+   */
+  async run() {
+    try {
+      this._lastResult = await this.detect();
+      return this._lastResult;
+    } catch (error) {
+      // Fail-safe: if detection throws, treat as not triggered
+      this._lastResult = {
+        triggered: false,
+        value: null,
+        confidence: 0,
+        error: error.message,
+      };
+      return this._lastResult;
+    }
+  }
+
+  /**
+   * Reset the signal state.
+   */
+  reset() {
+    this._lastResult = null;
+  }
+
+  /**
+   * Create a result object with defaults.
+   * @param {boolean} triggered - Whether the signal was triggered
+   * @param {*} [value=null] - Optional value associated with the detection
+   * @param {number} [confidence=1] - Confidence level (0-1)
+   * @returns {SignalResult}
+   */
+  createResult(triggered, value = null, confidence = 1) {
+    return {
+      triggered: Boolean(triggered),
+      value,
+      confidence: Math.max(0, Math.min(1, confidence)),
+    };
+  }
+}
+
+/**
+ * @typedef {Object} SignalResult
+ * @property {boolean} triggered - Whether the signal detected bot behavior
+ * @property {*} value - Associated value or evidence
+ * @property {number} confidence - Confidence level between 0 and 1
+ * @property {string} [error] - Error message if detection failed
+ */
+
+export { Signal };