@niksbanna/bot-detector 1.0.2 → 1.0.4

package/src/core/ScoringEngine.js

@@ -1,134 +0,0 @@
-/**
- * @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

@@ -1,181 +0,0 @@
-/**
- * @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 };

package/src/core/VerdictEngine.js

@@ -1,132 +0,0 @@
-/**
- * @fileoverview Verdict engine that determines bot/human classification.
- */
-
-/**
- * Possible verdicts from detection.
- * @enum {string}
- */
-const Verdict = {
-  HUMAN: 'human',
-  SUSPICIOUS: 'suspicious',
-  BOT: 'bot',
-};
-
-/**
- * Determines the final verdict based on score and triggered signals.
- */
-class VerdictEngine {
-  /**
-   * Default threshold configuration.
-   * @type {Object}
-   */
-  static DEFAULT_THRESHOLDS = {
-    human: 20,      // score < 20 = human
-    suspicious: 50, // 20 <= score < 50 = suspicious
-    // score >= 50 = bot
-  };
-
-  /**
-   * Creates a new VerdictEngine instance.
-   * @param {Object} [options={}] - Configuration options
-   * @param {number} [options.humanThreshold=20] - Max score for human verdict
-   * @param {number} [options.suspiciousThreshold=50] - Max score for suspicious verdict
-   * @param {Array<string>} [options.instantBotSignals=[]] - Signal IDs that instantly flag as bot
-   */
-  constructor(options = {}) {
-    this.humanThreshold = options.humanThreshold ?? VerdictEngine.DEFAULT_THRESHOLDS.human;
-    this.suspiciousThreshold = options.suspiciousThreshold ?? VerdictEngine.DEFAULT_THRESHOLDS.suspicious;
-    this.instantBotSignals = new Set(options.instantBotSignals || []);
-  }
-
-  /**
-   * Get the verdict based on score and triggered signals.
-   * @param {number} score - Calculated score (0-100)
-   * @param {Array<string>} triggeredSignals - List of triggered signal IDs
-   * @returns {VerdictResult}
-   */
-  getVerdict(score, triggeredSignals = []) {
-    // Check for instant bot signals first
-    for (const signalId of triggeredSignals) {
-      if (this.instantBotSignals.has(signalId)) {
-        return {
-          verdict: Verdict.BOT,
-          score,
-          confidence: 'high',
-          reason: `Instant bot signal triggered: ${signalId}`,
-          triggeredCount: triggeredSignals.length,
-        };
-      }
-    }
-
-    // Score-based verdict
-    let verdict;
-    let confidence;
-    let reason;
-
-    if (score < this.humanThreshold) {
-      verdict = Verdict.HUMAN;
-      confidence = score < 10 ? 'high' : 'medium';
-      reason = 'Low bot score';
-    } else if (score < this.suspiciousThreshold) {
-      verdict = Verdict.SUSPICIOUS;
-      confidence = 'medium';
-      reason = 'Moderate bot indicators detected';
-    } else {
-      verdict = Verdict.BOT;
-      confidence = score >= 75 ? 'high' : 'medium';
-      reason = 'High accumulation of bot indicators';
-    }
-
-    return {
-      verdict,
-      score,
-      confidence,
-      reason,
-      triggeredCount: triggeredSignals.length,
-    };
-  }
-
-  /**
-   * Check if signal should instantly flag as bot.
-   * @param {string} signalId - Signal identifier
-   * @returns {boolean}
-   */
-  isInstantBotSignal(signalId) {
-    return this.instantBotSignals.has(signalId);
-  }
-
-  /**
-   * Add a signal to the instant bot list.
-   * @param {string} signalId - Signal identifier
-   */
-  addInstantBotSignal(signalId) {
-    this.instantBotSignals.add(signalId);
-  }
-
-  /**
-   * Update thresholds.
-   * @param {Object} thresholds - New threshold values
-   * @param {number} [thresholds.human] - New human threshold
-   * @param {number} [thresholds.suspicious] - New suspicious threshold
-   */
-  setThresholds(thresholds) {
-    if (thresholds.human !== undefined) {
-      this.humanThreshold = thresholds.human;
-    }
-    if (thresholds.suspicious !== undefined) {
-      this.suspiciousThreshold = thresholds.suspicious;
-    }
-  }
-}
-
-/**
- * @typedef {Object} VerdictResult
- * @property {string} verdict - 'human', 'suspicious', or 'bot'
- * @property {number} score - The calculated score
- * @property {string} confidence - 'low', 'medium', or 'high'
- * @property {string} reason - Human-readable reason for verdict
- * @property {number} triggeredCount - Number of triggered signals
- */
-
-export { VerdictEngine, Verdict };

package/src/index.js

@@ -1,273 +0,0 @@
-/**
- * @fileoverview Main entry point for the bot detection library.
- * @module @niksbanna/bot-detector
- */
-
-// Core classes
-import { BotDetector, Verdict } from './core/BotDetector.js';
-import { Signal } from './core/Signal.js';
-import { ScoringEngine } from './core/ScoringEngine.js';
-import { VerdictEngine } from './core/VerdictEngine.js';
-
-// Environment signals
-import {
-  WebDriverSignal,
-  HeadlessSignal,
-  NavigatorAnomalySignal,
-  PermissionsSignal,
-} from './signals/environment/index.js';
-
-// Behavioral signals
-import {
-  MouseMovementSignal,
-  KeyboardPatternSignal,
-  InteractionTimingSignal,
-  ScrollBehaviorSignal,
-} from './signals/behavior/index.js';
-
-// Fingerprint signals
-import {
-  PluginsSignal,
-  WebGLSignal,
-  CanvasSignal,
-  AudioContextSignal,
-  ScreenSignal,
-} from './signals/fingerprint/index.js';
-
-// Timing signals
-import {
-  PageLoadSignal,
-  DOMContentTimingSignal,
-} from './signals/timing/index.js';
-
-// Automation framework signals
-import {
-  PuppeteerSignal,
-  PlaywrightSignal,
-  SeleniumSignal,
-  PhantomJSSignal,
-} from './signals/automation/index.js';
-
-/**
- * All built-in signal classes organized by category.
- */
-const Signals = {
-  // Environment signals
-  WebDriverSignal,
-  HeadlessSignal,
-  NavigatorAnomalySignal,
-  PermissionsSignal,
-  
-  // Behavioral signals
-  MouseMovementSignal,
-  KeyboardPatternSignal,
-  InteractionTimingSignal,
-  ScrollBehaviorSignal,
-  
-  // Fingerprint signals
-  PluginsSignal,
-  WebGLSignal,
-  CanvasSignal,
-  AudioContextSignal,
-  ScreenSignal,
-  
-  // Timing signals
-  PageLoadSignal,
-  DOMContentTimingSignal,
-  
-  // Automation framework signals
-  PuppeteerSignal,
-  PlaywrightSignal,
-  SeleniumSignal,
-  PhantomJSSignal,
-};
-
-/**
- * Default signal instances that don't require user interaction.
- * These are suitable for immediate detection on page load.
- */
-const defaultInstantSignals = [
-  new WebDriverSignal(),
-  new HeadlessSignal(),
-  new NavigatorAnomalySignal(),
-  new PermissionsSignal(),
-  new PluginsSignal(),
-  new WebGLSignal(),
-  new CanvasSignal(),
-  new AudioContextSignal(),
-  new ScreenSignal(),
-  new PageLoadSignal(),
-  new DOMContentTimingSignal(),
-  new PuppeteerSignal(),
-  new PlaywrightSignal(),
-  new SeleniumSignal(),
-  new PhantomJSSignal(),
-];
-
-/**
- * Signal instances that require user interaction to be meaningful.
- * These track mouse, keyboard, and scroll behavior over time.
- */
-const defaultInteractionSignals = [
-  new MouseMovementSignal(),
-  new KeyboardPatternSignal(),
-  new InteractionTimingSignal(),
-  new ScrollBehaviorSignal(),
-];
-
-/**
- * All default signal instances.
- */
-const defaultSignals = [...defaultInstantSignals, ...defaultInteractionSignals];
-
-/**
- * Create a BotDetector with all default signals registered.
- * This is the recommended way to create a detector for most use cases.
- * 
- * @param {Object} [options={}] - Configuration options
- * @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=['webdriver', 'puppeteer', 'playwright', 'selenium', 'phantomjs']] - Signals that instantly flag as bot
- * @param {boolean} [options.includeInteractionSignals=true] - Include signals requiring interaction
- * @param {number} [options.detectionTimeout=5000] - Timeout for detection in ms
- * @returns {BotDetector}
- * 
- * @example
- * // Basic usage
- * const detector = createDetector();
- * const result = await detector.detect();
- * 
- * @example
- * // Custom thresholds
- * const detector = createDetector({
- *   humanThreshold: 15,
- *   suspiciousThreshold: 40,
- * });
- * 
- * @example
- * // Skip interaction signals for instant detection
- * const detector = createDetector({
- *   includeInteractionSignals: false,
- * });
- */
-function createDetector(options = {}) {
-  const {
-    includeInteractionSignals = true,
-    instantBotSignals = ['webdriver', 'puppeteer', 'playwright', 'selenium', 'phantomjs'],
-    ...detectorOptions
-  } = options;
-
-  const signals = includeInteractionSignals 
-    ? [...defaultInstantSignals, ...defaultInteractionSignals.map(s => {
-        // Create fresh instances for interaction signals
-        const SignalClass = s.constructor;
-        return new SignalClass(s.options);
-      })]
-    : defaultInstantSignals.map(s => {
-        const SignalClass = s.constructor;
-        return new SignalClass(s.options);
-      });
-
-  return new BotDetector({
-    signals,
-    instantBotSignals,
-    ...detectorOptions,
-  });
-}
-
-/**
- * Quick detection function for simple use cases.
- * Creates a detector, runs detection, and returns result.
- * 
- * @param {Object} [options={}] - Detection options
- * @param {boolean} [options.skipInteractionSignals=false] - Skip signals requiring interaction
- * @returns {Promise<DetectionResult>}
- * 
- * @example
- * const result = await detect();
- * if (result.verdict === 'bot') {
- *   console.log('Bot detected!', result.score);
- * }
- */
-async function detect(options = {}) {
-  const detector = createDetector({
-    includeInteractionSignals: !options.skipInteractionSignals,
-  });
-  return detector.detect(options);
-}
-
-/**
- * Quick detection that only runs instant signals (no interaction required).
- * Suitable for immediate detection on page load.
- * 
- * @returns {Promise<DetectionResult>}
- * 
- * @example
- * document.addEventListener('DOMContentLoaded', async () => {
- *   const result = await detectInstant();
- *   console.log('Verdict:', result.verdict);
- * });
- */
-async function detectInstant() {
-  return detect({ skipInteractionSignals: true });
-}
-
-// Export everything
-export {
-  // Main class
-  BotDetector,
-  
-  // Factory functions
-  createDetector,
-  detect,
-  detectInstant,
-  
-  // Base classes
-  Signal,
-  ScoringEngine,
-  VerdictEngine,
-  
-  // Enums
-  Verdict,
-  
-  // Signal classes (for custom registration)
-  Signals,
-  
-  // Individual signals
-  WebDriverSignal,
-  HeadlessSignal,
-  NavigatorAnomalySignal,
-  PermissionsSignal,
-  MouseMovementSignal,
-  KeyboardPatternSignal,
-  InteractionTimingSignal,
-  ScrollBehaviorSignal,
-  PluginsSignal,
-  WebGLSignal,
-  CanvasSignal,
-  AudioContextSignal,
-  ScreenSignal,
-  PageLoadSignal,
-  DOMContentTimingSignal,
-  PuppeteerSignal,
-  PlaywrightSignal,
-  SeleniumSignal,
-  PhantomJSSignal,
-  
-  // Default signal instances
-  defaultSignals,
-  defaultInstantSignals,
-  defaultInteractionSignals,
-};
-
-// Default export for convenience
-export default {
-  BotDetector,
-  createDetector,
-  detect,
-  detectInstant,
-  Signal,
-  Signals,
-  Verdict,
-};