@niksbanna/bot-detector 1.0.3 → 1.0.4

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,281 +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;
-
-  // singletons. If two detectors share the same signal instances, calling
-  // detector1.reset() would corrupt detector2's cached results.
-  const signalClasses = includeInteractionSignals
-    ? [
-        WebDriverSignal, HeadlessSignal, NavigatorAnomalySignal, PermissionsSignal,
-        PluginsSignal, WebGLSignal, CanvasSignal, AudioContextSignal, ScreenSignal,
-        PageLoadSignal, DOMContentTimingSignal,
-        PuppeteerSignal, PlaywrightSignal, SeleniumSignal, PhantomJSSignal,
-        MouseMovementSignal, KeyboardPatternSignal, InteractionTimingSignal, ScrollBehaviorSignal,
-      ]
-    : [
-        WebDriverSignal, HeadlessSignal, NavigatorAnomalySignal, PermissionsSignal,
-        PluginsSignal, WebGLSignal, CanvasSignal, AudioContextSignal, ScreenSignal,
-        PageLoadSignal, DOMContentTimingSignal,
-        PuppeteerSignal, PlaywrightSignal, SeleniumSignal, PhantomJSSignal,
-      ];
-
-  const signals = signalClasses.map(Cls => new Cls());
-
-  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,
-};

package/src/signals/automation/PhantomJSSignal.js

@@ -1,135 +0,0 @@
-/**
- * @fileoverview Detects PhantomJS-specific artifacts.
- */
-
-import { Signal } from '../../core/Signal.js';
-
-/**
- * Detects artifacts left by PhantomJS.
- * PhantomJS is an older headless browser that leaves specific traces.
- */
-class PhantomJSSignal extends Signal {
-  static id = 'phantomjs';
-  static category = 'automation';
-  static weight = 1.0;
-  static description = 'Detects PhantomJS automation artifacts';
-
-  async detect() {
-    const indicators = [];
-    let confidence = 0;
-
-    // Check for PhantomJS globals
-    if (window.callPhantom) {
-      indicators.push('callPhantom');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    if (window._phantom) {
-      indicators.push('_phantom');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    if (window.phantom) {
-      indicators.push('phantom');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for PhantomJS in user agent
-    const ua = navigator.userAgent || '';
-    if (ua.includes('PhantomJS')) {
-      indicators.push('phantomjs-ua');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for PhantomJS specific properties
-    if (window.__phantomas) {
-      indicators.push('phantomas');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for CasperJS (built on PhantomJS)
-    if (window.__casper) {
-      indicators.push('casperjs');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    if (window.casper) {
-      indicators.push('casper-global');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for SlimerJS (PhantomJS alternative)
-    if (window.slimer) {
-      indicators.push('slimerjs');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for NightmareJS (Electron-based, similar patterns)
-    if (window.__nightmare) {
-      indicators.push('nightmare');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    if (window.nightmare) {
-      indicators.push('nightmare-global');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for function sources containing PhantomJS
-    try {
-      const funcString = Function.prototype.toString.call(Function);
-      if (funcString.includes('phantom') || funcString.includes('Phantom')) {
-        indicators.push('function-prototype-phantom');
-        confidence = Math.max(confidence, 0.8);
-      }
-    } catch (e) {
-      // Ignore errors
-    }
-
-    // Check for PhantomJS-specific behaviors
-    // PhantomJS has a specific way of handling errors
-    try {
-      throw new Error('test');
-    } catch (e) {
-      const stack = e.stack || '';
-      if (stack.includes('phantom')) {
-        indicators.push('stack-trace-phantom');
-        confidence = Math.max(confidence, 0.9);
-      }
-    }
-
-    // Check for PhantomJS-specific plugin handling
-    if (navigator.plugins && navigator.plugins.length === 0) {
-      // Combined with other PhantomJS indicators
-      if (indicators.length > 0) {
-        indicators.push('no-plugins-phantom');
-        confidence = Math.max(confidence, 0.5);
-      }
-    }
-
-    // Check for specific PhantomJS window properties.
-    const phantomProps = [
-      '__PHANTOM__',
-      'PHANTOM',
-    ];
-
-    for (const prop of phantomProps) {
-      if (prop in window) {
-        indicators.push(`phantom-prop-${prop.toLowerCase()}`);
-        confidence = Math.max(confidence, 0.9);
-      }
-    }
-
-    // Check for QtWebKit (PhantomJS engine)
-    if (ua.includes('QtWebKit')) {
-      indicators.push('qtwebkit');
-      confidence = Math.max(confidence, 0.7);
-    }
-
-    const triggered = indicators.length > 0;
-
-    return this.createResult(triggered, { indicators }, confidence);
-  }
-}
-
-export { PhantomJSSignal };

package/src/signals/automation/PlaywrightSignal.js

@@ -1,123 +0,0 @@
-/**
- * @fileoverview Detects Playwright-specific artifacts.
- */
-
-import { Signal } from '../../core/Signal.js';
-
-/**
- * Detects artifacts left by Playwright automation.
- * Playwright injects specific objects and leaves traces.
- */
-class PlaywrightSignal extends Signal {
-  static id = 'playwright';
-  static category = 'automation';
-  static weight = 1.0;
-  static description = 'Detects Playwright automation artifacts';
-
-  async detect() {
-    const indicators = [];
-    let confidence = 0;
-
-    // Check for Playwright namespace
-    if (window.__playwright) {
-      indicators.push('playwright-namespace');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for Playwright-injected objects
-    const playwrightGlobals = [
-      '__playwright',
-      '__pw_manual',
-      '__pwInitScripts',
-      'playwright',
-    ];
-
-    for (const global of playwrightGlobals) {
-      if (global in window) {
-        indicators.push(`global-${global}`);
-        confidence = Math.max(confidence, 1.0);
-      }
-    }
-
-    // Check for Playwright's binding pattern
-    if (window.__playwright__binding__) {
-      indicators.push('playwright-binding');
-      confidence = Math.max(confidence, 1.0);
-    }
-
-    // Check for Playwright-specific user agent markers
-    const ua = navigator.userAgent || '';
-    if (ua.includes('Playwright') || ua.includes('HeadlessChrome')) {
-      indicators.push('playwright-ua-marker');
-      confidence = Math.max(confidence, ua.includes('Playwright') ? 1.0 : 0.7);
-    }
-
-    // Check for Playwright's evaluate scope pattern
-    try {
-      // Playwright injects __pwBinding__ functions
-      const windowKeys = Object.keys(window);
-      const pwBindings = windowKeys.filter(k => k.startsWith('__pw'));
-      
-      if (pwBindings.length > 0) {
-        indicators.push('pw-bindings');
-        confidence = Math.max(confidence, 1.0);
-      }
-    } catch (e) {
-      // Ignore errors
-    }
-
-    // Check for Playwright's typical initialization patterns
-    if (typeof window.__pw_date_intercepted !== 'undefined') {
-      indicators.push('date-interception');
-      confidence = Math.max(confidence, 0.9);
-    }
-
-    // Check for Playwright's geolocation mock
-    if (window.__pw_geolocation__) {
-      indicators.push('geolocation-mock');
-      confidence = Math.max(confidence, 0.9);
-    }
-
-    // Check for Playwright's permission override
-    if (window.__pw_permissions__) {
-      indicators.push('permissions-override');
-      confidence = Math.max(confidence, 0.9);
-    }
-
-    // Check CDP session artifacts
-    if (window.__cdpSession__) {
-      indicators.push('cdp-session');
-      confidence = Math.max(confidence, 0.8);
-    }
-
-    // Check for error stack traces containing Playwright
-    try {
-      throw new Error('stack trace test');
-    } catch (e) {
-      const stack = e.stack || '';
-      if (stack.includes('playwright') || stack.includes('__pw')) {
-        indicators.push('stack-trace-playwright');
-        confidence = Math.max(confidence, 0.8);
-      }
-    }
-
-    // Check for Playwright's locale/timezone mocking
-    try {
-      const date = new Date();
-      const localeString = date.toLocaleString();
-      // Playwright often mocks timezone
-      if (window.__pwTimezone__) {
-        indicators.push('timezone-mock');
-        confidence = Math.max(confidence, 0.8);
-      }
-    } catch (e) {
-      // Ignore errors
-    }
-
-    const triggered = indicators.length > 0;
-
-    return this.createResult(triggered, { indicators }, confidence);
-  }
-}
-
-export { PlaywrightSignal };