@niksbanna/bot-detector 1.0.2 → 1.0.4

package/README.md

@@ -266,6 +266,28 @@ npm run dev
 
 ## Changelog
 
+### v1.0.4
+- **Optimization:** Drastically reduced npm package "unpacked size" (from ~1MB down to ~300KB) by disabling source map generation and excluding the raw `src/` directory from the published NPM tarball.
+
+### v1.0.3
+- **Stability Fixes:** 
+  - Fixed a major memory leak where `setTimeout` timers were never cleared in `BotDetector.detect()`.
+  - Fixed `getBreakdown()` calling `calculate()` in an $O(n^2)$ loop; now computes instantly ($O(n)$).
+  - Fixed an issue where multiple `BotDetector` instances on the same page shared mutable singleton state. `createDetector()` now guarantees fresh detection instances.
+  - `BotDetector.withDefaults()` now throws a descriptive error pointing to `createDetector()` instead of silently breaking and returning a useless detector.
+  - Capped tracking duration of all behavior signals (`MouseMovementSignal`, `KeyboardPatternSignal`, `ScrollBehaviorSignal`) at `2500ms` so they safely fit within the default `5000ms` global timeout without non-deterministic racing.
+- **False-Positive Fixes:**
+  - `PuppeteerSignal` & `HeadlessSignal`: Fixed a critical bug where `window.chrome.runtime` being undefined caused a false positive for all standard, non-extension Chrome users.
+  - `NavigatorAnomalySignal`: Chrome 110+ user-agent reduction returns `''` for `navigator.platform`; this is now correctly handled as normal behavior on Chrome.
+  - `PuppeteerSignal`: Increased `suspiciousBindings` threshold and excluded React, Webpack, Vite, Nuxt, and Next.js global prefixes to avoid false positives on heavy framework sites.
+  - `PageLoadSignal`: Fixed a "negative-timing" false positive caused by evaluating performance metrics before events had fired (zero epoch bug).
+  - `PageLoadSignal`: Fixed a "frozen-performance" false positive caused by the browser's deliberate Spectre timer quantization (1-2ms).
+- **Correctness Fixes:**
+  - Removed redundant `navigator.webdriver` checks from `PuppeteerSignal`, `PlaywrightSignal`, and `SeleniumSignal` to prevent triple-counting the same underlying signal; this check is now exclusively handled by `WebDriverSignal`.
+  - `PhantomJSSignal`: Cleaned up dead code evaluating `Buffer` and `process`.
+  - `DOMContentTimingSignal`: Randomized the ID of the injected test div to prevent detection scripts from keying off the hardcoded `__bot_detection_test__` id.
+- **Examples:** Fixed CORS issues with `file://` protocol in demo HTML files by utilizing the IIFE build instead of ESM imports.
+
 ### v1.0.2
 - **Fix:** `PuppeteerSignal` no longer false-positives on Angular apps — `__zone_symbol__*` bindings injected by Zone.js are now excluded from the suspicious-bindings check.
 - **Fix:** `PuppeteerSignal` no longer false-positives on normal Chrome pages — `incomplete-chrome-object` now only triggers when `window.chrome.runtime` is absent, not when `runtime.id` is undefined (which is normal outside of extensions).

package/dist/bot-detector.cjs.js

@@ -254,6 +254,7 @@ var ScoringEngine = class {
    */
   getBreakdown() {
     const breakdown = [];
+    const score = this.calculate();
     for (const [signalId, data] of this._results) {
       breakdown.push({
         signalId,
@@ -261,7 +262,7 @@ var ScoringEngine = class {
         confidence: data.confidence,
         weight: data.weight,
         contribution: data.contribution,
-        percentOfScore: this.calculate() > 0 ? (data.contribution / this.calculate() * 100).toFixed(1) : "0.0"
+        percentOfScore: score > 0 ? (data.contribution / score * 100).toFixed(1) : "0.0"
       });
     }
     return breakdown.sort((a, b) => b.contribution - a.contribution);
@@ -404,7 +405,7 @@ __publicField(_VerdictEngine, "DEFAULT_THRESHOLDS", {
 var VerdictEngine = _VerdictEngine;
 
 // src/core/BotDetector.js
-var BotDetector = class _BotDetector {
+var BotDetector = class {
   /**
    * Creates a new BotDetector instance.
    * @param {Object} [options={}] - Configuration options
@@ -517,17 +518,17 @@ var BotDetector = class _BotDetector {
         return true;
       });
       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)
-          )
-        ]);
+        let timeoutId;
+        const timeoutPromise = new Promise((resolve) => {
+          timeoutId = setTimeout(() => resolve({
+            triggered: false,
+            value: null,
+            confidence: 0,
+            error: "timeout"
+          }), this._detectionTimeout);
+        });
+        const result = await Promise.race([signal.run(), timeoutPromise]);
+        clearTimeout(timeoutId);
         return { signal, result };
       });
       const results = await Promise.all(detectionPromises);
@@ -614,12 +615,20 @@ var BotDetector = class _BotDetector {
     }
   }
   /**
-   * Create a detector with default signals.
-   * @param {Object} [options={}] - Configuration options
-   * @returns {BotDetector}
+   * @deprecated Use `createDetector()` from '@niksbanna/bot-detector' instead.
+   * This method cannot load default signals from here due to module boundaries.
+   * 
+   * @example
+   * // Correct:
+   * import { createDetector } from '@niksbanna/bot-detector';
+   * const detector = createDetector();
+   * 
+   * @throws {Error} Always — to prevent silent empty-detector bugs.
    */
-  static withDefaults(options = {}) {
-    return new _BotDetector(options);
+  static withDefaults() {
+    throw new Error(
+      "BotDetector.withDefaults() is not supported. Use createDetector() from '@niksbanna/bot-detector' instead:\n  import { createDetector } from '@niksbanna/bot-detector';\n  const detector = createDetector();"
+    );
   }
 };
 
@@ -675,9 +684,6 @@ var HeadlessSignal = class extends Signal {
       if (typeof window.chrome === "undefined") {
         indicators.push("missing-chrome-object");
         confidence = Math.max(confidence, 0.6);
-      } else if (!window.chrome.runtime) {
-        indicators.push("missing-chrome-runtime");
-        confidence = Math.max(confidence, 0.4);
       }
     }
     if (navigator.plugins && navigator.plugins.length === 0) {
@@ -743,7 +749,8 @@ var NavigatorAnomalySignal = class extends Signal {
       totalScore += 1;
     }
     checksPerformed++;
-    if (!platform || platform === "" || platform === "undefined") {
+    const isModernChrome = ua.includes("Chrome") && !ua.includes("Chromium");
+    if (!isModernChrome && (!platform || platform === "" || platform === "undefined")) {
       anomalies.push("empty-platform");
       totalScore += 1;
     }
@@ -855,7 +862,7 @@ var MouseMovementSignal = class extends Signal {
     super(options);
     this._movements = [];
     this._isTracking = false;
-    this._trackingDuration = options.trackingDuration || 3e3;
+    this._trackingDuration = Math.min(options.trackingDuration || 2500, 2500);
     this._minMovements = options.minMovements || 5;
     this._boundHandler = null;
   }
@@ -1009,7 +1016,7 @@ var KeyboardPatternSignal = class extends Signal {
     super(options);
     this._keystrokes = [];
     this._isTracking = false;
-    this._trackingDuration = options.trackingDuration || 5e3;
+    this._trackingDuration = Math.min(options.trackingDuration || 2500, 2500);
     this._minKeystrokes = options.minKeystrokes || 10;
     this._boundKeydownHandler = null;
     this._boundKeyupHandler = null;
@@ -1304,7 +1311,7 @@ var ScrollBehaviorSignal = class extends Signal {
     super(options);
     this._scrollEvents = [];
     this._isTracking = false;
-    this._trackingDuration = options.trackingDuration || 3e3;
+    this._trackingDuration = Math.min(options.trackingDuration || 2500, 2500);
     this._boundHandler = null;
   }
   /**
@@ -1968,22 +1975,26 @@ var PageLoadSignal = class extends Signal {
     }
     const timing = performance.timing;
     const navigationStart = timing.navigationStart;
-    const domContentLoaded = timing.domContentLoadedEventEnd - navigationStart;
-    const domComplete = timing.domComplete - navigationStart;
-    const loadComplete = timing.loadEventEnd - navigationStart;
-    const dnsLookup = timing.domainLookupEnd - timing.domainLookupStart;
-    const tcpConnection = timing.connectEnd - timing.connectStart;
-    const serverResponse = timing.responseEnd - timing.requestStart;
-    const domProcessing = timing.domComplete - timing.domLoading;
-    if (domContentLoaded > 0 && domContentLoaded < 10) {
+    const safeTimingDiff = (end, start) => {
+      if (end === 0 || start === 0) return null;
+      return end - start;
+    };
+    const domContentLoaded = safeTimingDiff(timing.domContentLoadedEventEnd, navigationStart);
+    const domComplete = safeTimingDiff(timing.domComplete, navigationStart);
+    const loadComplete = safeTimingDiff(timing.loadEventEnd, navigationStart);
+    const dnsLookup = safeTimingDiff(timing.domainLookupEnd, timing.domainLookupStart);
+    const tcpConnection = safeTimingDiff(timing.connectEnd, timing.connectStart);
+    const serverResponse = safeTimingDiff(timing.responseEnd, timing.requestStart);
+    const domProcessing = safeTimingDiff(timing.domComplete, timing.domLoading);
+    if (domContentLoaded !== null && domContentLoaded > 0 && domContentLoaded < 10) {
       anomalies.push("instant-dom-content-loaded");
       confidence = Math.max(confidence, 0.7);
     }
-    if (dnsLookup === 0 && tcpConnection === 0 && serverResponse < 5) {
+    if (dnsLookup === 0 && tcpConnection === 0 && serverResponse !== null && serverResponse < 5) {
       anomalies.push("zero-network-timing");
       confidence = Math.max(confidence, 0.4);
     }
-    if (domContentLoaded < 0 || domComplete < 0 || loadComplete < 0) {
+    if (domContentLoaded !== null && domContentLoaded < 0 || domComplete !== null && domComplete < 0 || loadComplete !== null && loadComplete < 0) {
       anomalies.push("negative-timing");
       confidence = Math.max(confidence, 0.8);
     }
@@ -1993,18 +2004,21 @@ var PageLoadSignal = class extends Signal {
         confidence = Math.max(confidence, 0.7);
       }
     }
-    if (domProcessing > 3e4) {
+    if (domProcessing !== null && domProcessing > 3e4) {
       anomalies.push("excessive-dom-processing");
       confidence = Math.max(confidence, 0.3);
     }
     const scriptsLoadedTime = timing.domContentLoadedEventStart - timing.responseEnd;
-    if (scriptsLoadedTime > 0 && scriptsLoadedTime < 5) {
+    if (timing.responseEnd > 0 && timing.domContentLoadedEventStart > 0 && scriptsLoadedTime > 0 && scriptsLoadedTime < 5) {
       anomalies.push("instant-script-execution");
       confidence = Math.max(confidence, 0.4);
     }
-    const perfNow1 = performance.now();
-    const perfNow2 = performance.now();
-    if (perfNow1 === perfNow2 && perfNow1 > 0) {
+    const perfBefore = performance.now();
+    const spinEnd = perfBefore + 2;
+    while (performance.now() < spinEnd) {
+    }
+    const perfAfter = performance.now();
+    if (perfAfter === perfBefore) {
       anomalies.push("frozen-performance-now");
       confidence = Math.max(confidence, 0.6);
     }
@@ -2114,9 +2128,10 @@ var DOMContentTimingSignal = class extends Signal {
       confidence = Math.max(confidence, 0.4);
     }
     try {
+      const randomId = `__bdt_${Math.random().toString(36).slice(2)}`;
       const startMutation = performance.now();
       const testDiv = document.createElement("div");
-      testDiv.id = "__bot_detection_test__";
+      testDiv.id = randomId;
       document.body.appendChild(testDiv);
       const afterAppend = performance.now();
       document.body.removeChild(testDiv);
@@ -2226,23 +2241,30 @@ var PuppeteerSignal = class extends Signal {
       indicators.push("default-viewport");
       confidence = Math.max(confidence, 0.3);
     }
-    if (navigator.webdriver === true) {
-      indicators.push("webdriver-flag");
-      confidence = Math.max(confidence, 0.9);
-    }
+    const FRAMEWORK_PREFIXES = [
+      "__zone_symbol__",
+      // Angular / Zone.js
+      "__next",
+      // Next.js
+      "__webpack",
+      // webpack
+      "__react",
+      // React DevTools
+      "__REACT",
+      "__vite",
+      // Vite
+      "__nuxt"
+      // Nuxt.js
+    ];
     const suspiciousBindings = Object.keys(window).filter((key) => {
-      return key.startsWith("__") && !key.startsWith("__zone_symbol__") && typeof window[key] === "function";
+      if (!key.startsWith("__")) return false;
+      if (typeof window[key] !== "function") return false;
+      return !FRAMEWORK_PREFIXES.some((prefix) => key.startsWith(prefix));
     });
-    if (suspiciousBindings.length > 5) {
+    if (suspiciousBindings.length > 10) {
       indicators.push("suspicious-bindings");
       confidence = Math.max(confidence, 0.5);
     }
-    if (typeof window.chrome !== "undefined") {
-      if (!window.chrome.runtime) {
-        indicators.push("incomplete-chrome-object");
-        confidence = Math.max(confidence, 0.4);
-      }
-    }
     const triggered = indicators.length > 0;
     return this.createResult(triggered, { indicators }, confidence);
   }
@@ -2282,10 +2304,6 @@ var PlaywrightSignal = class extends Signal {
       indicators.push("playwright-ua-marker");
       confidence = Math.max(confidence, ua.includes("Playwright") ? 1 : 0.7);
     }
-    if (navigator.webdriver === true) {
-      indicators.push("webdriver-flag");
-      confidence = Math.max(confidence, 0.8);
-    }
     try {
       const windowKeys = Object.keys(window);
       const pwBindings = windowKeys.filter((k) => k.startsWith("__pw"));
@@ -2343,10 +2361,6 @@ var SeleniumSignal = class extends Signal {
   async detect() {
     const indicators = [];
     let confidence = 0;
-    if (navigator.webdriver === true) {
-      indicators.push("webdriver-flag");
-      confidence = Math.max(confidence, 1);
-    }
     const seleniumGlobals = [
       "_selenium",
       "callSelenium",
@@ -2513,14 +2527,10 @@ var PhantomJSSignal = class extends Signal {
     }
     const phantomProps = [
       "__PHANTOM__",
-      "PHANTOM",
-      "Buffer",
-      // PhantomJS exposes Node.js Buffer
-      "process"
-      // May expose Node.js process
+      "PHANTOM"
     ];
     for (const prop of phantomProps) {
-      if (prop in window && prop !== "Buffer" && prop !== "process") {
+      if (prop in window) {
         indicators.push(`phantom-prop-${prop.toLowerCase()}`);
         confidence = Math.max(confidence, 0.9);
       }
@@ -2595,13 +2605,44 @@ function createDetector(options = {}) {
     instantBotSignals = ["webdriver", "puppeteer", "playwright", "selenium", "phantomjs"],
     ...detectorOptions
   } = options;
-  const signals = includeInteractionSignals ? [...defaultInstantSignals, ...defaultInteractionSignals.map((s) => {
-    const SignalClass = s.constructor;
-    return new SignalClass(s.options);
-  })] : defaultInstantSignals.map((s) => {
-    const SignalClass = s.constructor;
-    return new SignalClass(s.options);
-  });
+  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,
@@ -2626,4 +2667,3 @@ var index_default = {
   Signals,
   Verdict
 };
-//# sourceMappingURL=bot-detector.cjs.js.map