@niksbanna/bot-detector 1.0.0

package/src/signals/environment/PermissionsSignal.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Detects permissions API anomalies.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Detects anomalies in the Permissions API.
+ * Automation tools often have inconsistent permission states.
+ */
+class PermissionsSignal extends Signal {
+  static id = 'permissions';
+  static category = 'environment';
+  static weight = 0.5;
+  static description = 'Detects Permissions API anomalies';
+
+  async detect() {
+    const anomalies = [];
+    
+    // Check if Permissions API exists
+    if (!navigator.permissions) {
+      // Not an anomaly, just not supported
+      return this.createResult(false, { supported: false }, 0);
+    }
+
+    try {
+      // Check notification permission consistency
+      const notificationStatus = await navigator.permissions.query({ name: 'notifications' });
+      
+      if (typeof Notification !== 'undefined') {
+        const directPermission = Notification.permission;
+        
+        // Check for mismatch
+        if ((directPermission === 'granted' && notificationStatus.state !== 'granted') ||
+            (directPermission === 'denied' && notificationStatus.state !== 'denied') ||
+            (directPermission === 'default' && notificationStatus.state !== 'prompt')) {
+          anomalies.push('notification-permission-mismatch');
+        }
+      }
+
+      // Check geolocation permission if available
+      try {
+        const geoStatus = await navigator.permissions.query({ name: 'geolocation' });
+        // In automation, geolocation is often pre-denied without user action
+        if (geoStatus.state === 'denied' && window.outerWidth === 0) {
+          anomalies.push('geo-denied-headless');
+        }
+      } catch (e) {
+        // Geolocation permission query may not be supported
+      }
+
+      // Check if permission.query throws on valid permission
+      try {
+        await navigator.permissions.query({ name: 'camera' });
+      } catch (e) {
+        // Some headless browsers don't support camera permission
+        if (e.name === 'TypeError') {
+          anomalies.push('camera-permission-error');
+        }
+      }
+
+    } catch (e) {
+      // If permissions query throws unexpectedly, that's suspicious
+      if (e.name !== 'TypeError') {
+        anomalies.push('permissions-query-error');
+      }
+    }
+
+    const triggered = anomalies.length > 0;
+    const confidence = Math.min(1, anomalies.length * 0.4);
+
+    return this.createResult(triggered, { anomalies }, confidence);
+  }
+}
+
+export { PermissionsSignal };

package/src/signals/environment/WebDriverSignal.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Detects navigator.webdriver property.
+ * This is the most reliable indicator of WebDriver-controlled browsers.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Detects the presence of navigator.webdriver property.
+ * This property is set to true by automation frameworks like Selenium, Puppeteer, and Playwright.
+ */
+class WebDriverSignal extends Signal {
+  static id = 'webdriver';
+  static category = 'environment';
+  static weight = 1.0;
+  static description = 'Detects navigator.webdriver automation flag';
+
+  async detect() {
+    // Direct check
+    if (navigator.webdriver === true) {
+      return this.createResult(true, { webdriver: true }, 1.0);
+    }
+
+    // Check if property exists but is hidden/modified
+    const descriptor = Object.getOwnPropertyDescriptor(navigator, 'webdriver');
+    if (descriptor) {
+      // Property exists - check if it's been tampered with
+      if (descriptor.get || !descriptor.configurable) {
+        return this.createResult(true, { 
+          webdriver: 'modified',
+          descriptor: {
+            configurable: descriptor.configurable,
+            enumerable: descriptor.enumerable,
+            hasGetter: !!descriptor.get,
+          }
+        }, 0.8);
+      }
+    }
+
+    // Check prototype chain for webdriver
+    try {
+      const proto = Object.getPrototypeOf(navigator);
+      const protoDescriptor = Object.getOwnPropertyDescriptor(proto, 'webdriver');
+      if (protoDescriptor && protoDescriptor.get) {
+        const value = protoDescriptor.get.call(navigator);
+        if (value === true) {
+          return this.createResult(true, { webdriver: true, source: 'prototype' }, 1.0);
+        }
+      }
+    } catch (e) {
+      // Some environments may throw on prototype access
+    }
+
+    return this.createResult(false);
+  }
+}
+
+export { WebDriverSignal };

package/src/signals/environment/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Environment signals index.
+ */
+
+export { WebDriverSignal } from './WebDriverSignal.js';
+export { HeadlessSignal } from './HeadlessSignal.js';
+export { NavigatorAnomalySignal } from './NavigatorAnomalySignal.js';
+export { PermissionsSignal } from './PermissionsSignal.js';

package/src/signals/fingerprint/AudioContextSignal.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Detects AudioContext anomalies.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Checks for AudioContext anomalies.
+ * Bots and headless browsers often have unusual or missing audio capabilities.
+ */
+class AudioContextSignal extends Signal {
+  static id = 'audio-context';
+  static category = 'fingerprint';
+  static weight = 0.5;
+  static description = 'Detects AudioContext anomalies';
+
+  async detect() {
+    const anomalies = [];
+    let confidence = 0;
+
+    // Check if AudioContext exists
+    const AudioContext = window.AudioContext || window.webkitAudioContext;
+    
+    if (!AudioContext) {
+      // AudioContext not available
+      anomalies.push('audio-context-unavailable');
+      confidence = Math.max(confidence, 0.4);
+      return this.createResult(true, { anomalies }, confidence);
+    }
+
+    let audioContext = null;
+    let oscillator = null;
+    let analyser = null;
+
+    try {
+      audioContext = new AudioContext();
+      
+      // Check sample rate - unusual values may indicate virtualization
+      const sampleRate = audioContext.sampleRate;
+      if (sampleRate !== 44100 && sampleRate !== 48000 && sampleRate !== 96000) {
+        anomalies.push('unusual-sample-rate');
+        confidence = Math.max(confidence, 0.3);
+      }
+
+      // Check for suspended state (auto-play policy)
+      // This is normal, but combined with other factors can be suspicious
+
+      // Try to create an oscillator and check its properties
+      oscillator = audioContext.createOscillator();
+      analyser = audioContext.createAnalyser();
+      
+      if (!oscillator || !analyser) {
+        anomalies.push('audio-nodes-unavailable');
+        confidence = Math.max(confidence, 0.5);
+      } else {
+        // Check analyser properties
+        const fftSize = analyser.fftSize;
+        if (fftSize !== 2048) {
+          // Non-default value might indicate tampering
+          // but this alone isn't conclusive
+        }
+
+        // Check destination
+        const destination = audioContext.destination;
+        if (!destination || destination.maxChannelCount === 0) {
+          anomalies.push('no-audio-destination');
+          confidence = Math.max(confidence, 0.6);
+        }
+
+        // Check for channel count
+        if (destination && destination.maxChannelCount < 2) {
+          anomalies.push('mono-audio-only');
+          confidence = Math.max(confidence, 0.3);
+        }
+      }
+
+      // Check for overridden AudioContext
+      try {
+        const audioCtxStr = AudioContext.toString();
+        if (!audioCtxStr.includes('[native code]')) {
+          anomalies.push('audio-context-overridden');
+          confidence = Math.max(confidence, 0.7);
+        }
+      } catch (e) {
+        // Some environments may throw
+      }
+
+      // Audio fingerprint test - create a noise signal and check output
+      try {
+        if (audioContext.state === 'suspended') {
+          // Try to resume (may not work without user gesture)
+          await audioContext.resume().catch(() => {});
+        }
+
+        // Only perform if we can
+        if (audioContext.state === 'running') {
+          const oscillatorNode = audioContext.createOscillator();
+          const gainNode = audioContext.createGain();
+          const scriptProcessor = audioContext.createScriptProcessor 
+            ? audioContext.createScriptProcessor(4096, 1, 1)
+            : null;
+
+          if (scriptProcessor) {
+            oscillatorNode.type = 'triangle';
+            oscillatorNode.frequency.value = 10000;
+            gainNode.gain.value = 0;
+            
+            oscillatorNode.connect(gainNode);
+            gainNode.connect(scriptProcessor);
+            scriptProcessor.connect(audioContext.destination);
+
+            // Brief test
+            oscillatorNode.start(0);
+            
+            await new Promise(resolve => setTimeout(resolve, 50));
+            
+            oscillatorNode.stop();
+            oscillatorNode.disconnect();
+            gainNode.disconnect();
+            scriptProcessor.disconnect();
+          }
+        }
+      } catch (e) {
+        // Audio fingerprinting blocked or failed
+        anomalies.push('audio-fingerprint-blocked');
+        confidence = Math.max(confidence, 0.4);
+      }
+
+      // Check for OfflineAudioContext
+      const OfflineAudioContext = window.OfflineAudioContext || window.webkitOfflineAudioContext;
+      if (!OfflineAudioContext) {
+        anomalies.push('offline-audio-context-unavailable');
+        confidence = Math.max(confidence, 0.3);
+      }
+
+    } catch (e) {
+      anomalies.push('audio-context-error');
+      confidence = Math.max(confidence, 0.4);
+    } finally {
+      // Clean up
+      if (oscillator) {
+        try { oscillator.disconnect(); } catch (e) {}
+      }
+      if (analyser) {
+        try { analyser.disconnect(); } catch (e) {}
+      }
+      if (audioContext) {
+        try { audioContext.close(); } catch (e) {}
+      }
+    }
+
+    const triggered = anomalies.length > 0;
+
+    return this.createResult(triggered, { anomalies }, confidence);
+  }
+}
+
+export { AudioContextSignal };

package/src/signals/fingerprint/CanvasSignal.js

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Detects canvas fingerprint blocking or spoofing.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Detects canvas manipulation, blocking, or spoofing.
+ * Privacy tools and some bots modify canvas output.
+ */
+class CanvasSignal extends Signal {
+  static id = 'canvas';
+  static category = 'fingerprint';
+  static weight = 0.5;
+  static description = 'Detects canvas fingerprint anomalies';
+
+  async detect() {
+    const anomalies = [];
+    let confidence = 0;
+
+    try {
+      const canvas = document.createElement('canvas');
+      canvas.width = 200;
+      canvas.height = 50;
+      
+      const ctx = canvas.getContext('2d');
+      if (!ctx) {
+        anomalies.push('canvas-context-unavailable');
+        confidence = Math.max(confidence, 0.5);
+        return this.createResult(true, { anomalies }, confidence);
+      }
+
+      // Draw a complex pattern for fingerprinting
+      ctx.textBaseline = 'alphabetic';
+      ctx.font = '14px Arial';
+      ctx.fillStyle = '#f60';
+      ctx.fillRect(0, 0, 200, 50);
+      ctx.fillStyle = '#069';
+      ctx.fillText('Bot Detection Test 🤖', 2, 15);
+      ctx.fillStyle = 'rgba(102, 204, 0, 0.7)';
+      ctx.fillText('Canvas Fingerprint', 4, 30);
+      
+      // Add some complex graphics
+      ctx.beginPath();
+      ctx.arc(100, 25, 10, 0, Math.PI * 2, true);
+      ctx.closePath();
+      ctx.fill();
+
+      // Get data URL
+      const dataUrl1 = canvas.toDataURL();
+
+      // Draw again - should produce same result
+      ctx.clearRect(0, 0, 200, 50);
+      ctx.fillStyle = '#f60';
+      ctx.fillRect(0, 0, 200, 50);
+      ctx.fillStyle = '#069';
+      ctx.fillText('Bot Detection Test 🤖', 2, 15);
+      ctx.fillStyle = 'rgba(102, 204, 0, 0.7)';
+      ctx.fillText('Canvas Fingerprint', 4, 30);
+      ctx.beginPath();
+      ctx.arc(100, 25, 10, 0, Math.PI * 2, true);
+      ctx.closePath();
+      ctx.fill();
+
+      const dataUrl2 = canvas.toDataURL();
+
+      // If results differ, canvas is being randomized (privacy protection)
+      if (dataUrl1 !== dataUrl2) {
+        anomalies.push('canvas-randomized');
+        confidence = Math.max(confidence, 0.6);
+      }
+
+      // Check for blank canvas (blocking)
+      if (dataUrl1.length < 1000) {
+        anomalies.push('canvas-possibly-blank');
+        confidence = Math.max(confidence, 0.4);
+      }
+
+      // Check for common blocked canvas signature
+      const blankCanvas = document.createElement('canvas');
+      blankCanvas.width = 200;
+      blankCanvas.height = 50;
+      const blankUrl = blankCanvas.toDataURL();
+      
+      if (dataUrl1 === blankUrl) {
+        anomalies.push('canvas-rendering-blocked');
+        confidence = Math.max(confidence, 0.7);
+      }
+
+      // Check for toDataURL being overridden
+      try {
+        const toDataURLStr = canvas.toDataURL.toString();
+        if (!toDataURLStr.includes('[native code]')) {
+          anomalies.push('toDataURL-overridden');
+          confidence = Math.max(confidence, 0.8);
+        }
+      } catch (e) {
+        // Some environments may throw
+      }
+
+      // Check pixel data directly
+      const imageData = ctx.getImageData(0, 0, 200, 50);
+      const pixels = imageData.data;
+      
+      // Check if all pixels are the same (completely blocked)
+      let allSame = true;
+      const firstPixel = [pixels[0], pixels[1], pixels[2], pixels[3]];
+      for (let i = 4; i < pixels.length; i += 4) {
+        if (pixels[i] !== firstPixel[0] || 
+            pixels[i+1] !== firstPixel[1] || 
+            pixels[i+2] !== firstPixel[2]) {
+          allSame = false;
+          break;
+        }
+      }
+      
+      if (allSame) {
+        anomalies.push('uniform-pixel-data');
+        confidence = Math.max(confidence, 0.6);
+      }
+
+    } catch (e) {
+      anomalies.push('canvas-error');
+      confidence = Math.max(confidence, 0.4);
+    }
+
+    const triggered = anomalies.length > 0;
+
+    return this.createResult(triggered, { anomalies }, confidence);
+  }
+}
+
+export { CanvasSignal };

package/src/signals/fingerprint/PluginsSignal.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Detects browser plugin anomalies.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Checks for empty or suspicious plugin configurations.
+ * Headless browsers and bots often have no plugins.
+ */
+class PluginsSignal extends Signal {
+  static id = 'plugins';
+  static category = 'fingerprint';
+  static weight = 0.6;
+  static description = 'Detects browser plugin anomalies';
+
+  async detect() {
+    const anomalies = [];
+    let confidence = 0;
+
+    const plugins = navigator.plugins;
+    const mimeTypes = navigator.mimeTypes;
+
+    // Check if plugins exists
+    if (!plugins) {
+      anomalies.push('no-plugins-object');
+      confidence = Math.max(confidence, 0.6);
+      return this.createResult(true, { anomalies }, confidence);
+    }
+
+    // Check for empty plugins array
+    if (plugins.length === 0) {
+      anomalies.push('empty-plugins');
+      confidence = Math.max(confidence, 0.5);
+    }
+
+    // Check for Chrome-specific plugins in Chrome browser
+    const ua = navigator.userAgent || '';
+    if (ua.includes('Chrome') && !ua.includes('Chromium')) {
+      // Real Chrome typically has at least these plugins
+      const hasChromePdf = Array.from(plugins).some(p => 
+        p.name.includes('PDF') || p.name.includes('Chromium PDF'));
+      
+      if (!hasChromePdf && plugins.length === 0) {
+        anomalies.push('chrome-missing-pdf-plugin');
+        confidence = Math.max(confidence, 0.4);
+      }
+    }
+
+    // Check for consistent plugin/mimeType relationship
+    if (plugins.length > 0 && mimeTypes) {
+      let totalMimeTypes = 0;
+      for (let i = 0; i < plugins.length; i++) {
+        totalMimeTypes += plugins[i].length || 0;
+      }
+
+      // Plugins exist but no mimeTypes
+      if (mimeTypes.length === 0 && totalMimeTypes > 0) {
+        anomalies.push('mimetypes-mismatch');
+        confidence = Math.max(confidence, 0.5);
+      }
+    }
+
+    // Check for identical plugin names (sign of spoofing)
+    if (plugins.length > 1) {
+      const names = Array.from(plugins).map(p => p.name);
+      const uniqueNames = new Set(names);
+      if (uniqueNames.size < names.length) {
+        anomalies.push('duplicate-plugins');
+        confidence = Math.max(confidence, 0.6);
+      }
+    }
+
+    // Check for plugin array tampering
+    try {
+      const desc = Object.getOwnPropertyDescriptor(Navigator.prototype, 'plugins');
+      if (desc && desc.get) {
+        // Check if it's been overridden
+        const nativeToString = desc.get.toString();
+        if (!nativeToString.includes('[native code]')) {
+          anomalies.push('plugins-getter-overridden');
+          confidence = Math.max(confidence, 0.7);
+        }
+      }
+    } catch (e) {
+      // Ignore errors during introspection
+    }
+
+    // Check for suspiciously few plugins in a desktop browser
+    const isMobile = /Android|iPhone|iPad|iPod|Mobile/i.test(ua);
+    if (!isMobile && plugins.length === 1) {
+      anomalies.push('minimal-plugins');
+      confidence = Math.max(confidence, 0.3);
+    }
+
+    const triggered = anomalies.length > 0;
+
+    return this.createResult(triggered, {
+      anomalies,
+      pluginCount: plugins.length,
+      mimeTypeCount: mimeTypes?.length || 0,
+    }, confidence);
+  }
+}
+
+export { PluginsSignal };

package/src/signals/fingerprint/ScreenSignal.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Detects unusual screen and window dimensions.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Detects screen dimension anomalies.
+ * Bots and headless browsers often have unusual screen configurations.
+ */
+class ScreenSignal extends Signal {
+  static id = 'screen';
+  static category = 'fingerprint';
+  static weight = 0.4;
+  static description = 'Detects unusual screen dimensions';
+
+  async detect() {
+    const anomalies = [];
+    let confidence = 0;
+
+    const screen = window.screen;
+    if (!screen) {
+      anomalies.push('no-screen-object');
+      confidence = Math.max(confidence, 0.6);
+      return this.createResult(true, { anomalies }, confidence);
+    }
+
+    const width = screen.width;
+    const height = screen.height;
+    const availWidth = screen.availWidth;
+    const availHeight = screen.availHeight;
+    const colorDepth = screen.colorDepth;
+    const pixelDepth = screen.pixelDepth;
+    const outerWidth = window.outerWidth;
+    const outerHeight = window.outerHeight;
+    const innerWidth = window.innerWidth;
+    const innerHeight = window.innerHeight;
+
+    // Check for zero dimensions (headless indicator)
+    if (outerWidth === 0 || outerHeight === 0) {
+      anomalies.push('zero-outer-dimensions');
+      confidence = Math.max(confidence, 0.8);
+    }
+
+    if (innerWidth === 0 || innerHeight === 0) {
+      anomalies.push('zero-inner-dimensions');
+      confidence = Math.max(confidence, 0.7);
+    }
+
+    // Check for very small screen (unrealistic for desktop)
+    const ua = navigator.userAgent || '';
+    const isMobile = /Android|iPhone|iPad|iPod|Mobile/i.test(ua);
+    
+    if (!isMobile && (width < 640 || height < 480)) {
+      anomalies.push('very-small-screen');
+      confidence = Math.max(confidence, 0.5);
+    }
+
+    // Check for very large screen (unrealistic)
+    if (width > 7680 || height > 4320) { // Beyond 8K
+      anomalies.push('unrealistic-screen-size');
+      confidence = Math.max(confidence, 0.4);
+    }
+
+    // Check for common headless default dimensions
+    const headlessDefaults = [
+      { w: 800, h: 600 },
+      { w: 1024, h: 768 },
+      { w: 1920, h: 1080 },
+    ];
+
+    for (const def of headlessDefaults) {
+      if (width === def.w && height === def.h && 
+          outerWidth === def.w && outerHeight === def.h) {
+        // Exact match with no browser chrome - suspicious
+        anomalies.push('headless-default-dimensions');
+        confidence = Math.max(confidence, 0.5);
+        break;
+      }
+    }
+
+    // Check for screen larger than available (impossible)
+    if (availWidth > width || availHeight > height) {
+      anomalies.push('available-exceeds-total');
+      confidence = Math.max(confidence, 0.7);
+    }
+
+    // Check for window larger than screen
+    if (outerWidth > width || outerHeight > height) {
+      anomalies.push('window-exceeds-screen');
+      confidence = Math.max(confidence, 0.6);
+    }
+
+    // Check for unusual color depth
+    if (colorDepth !== 24 && colorDepth !== 32 && colorDepth !== 30 && colorDepth !== 48) {
+      anomalies.push('unusual-color-depth');
+      confidence = Math.max(confidence, 0.3);
+    }
+
+    // Check for mismatched color/pixel depth
+    if (colorDepth !== pixelDepth) {
+      anomalies.push('depth-mismatch');
+      confidence = Math.max(confidence, 0.3);
+    }
+
+    // Check for device pixel ratio anomalies
+    const dpr = window.devicePixelRatio;
+    if (dpr === 0 || dpr === undefined) {
+      anomalies.push('missing-device-pixel-ratio');
+      confidence = Math.max(confidence, 0.5);
+    } else if (dpr < 0.5 || dpr > 5) {
+      anomalies.push('unusual-device-pixel-ratio');
+      confidence = Math.max(confidence, 0.4);
+    }
+
+    // Check for screen orientation API anomalies
+    if (screen.orientation) {
+      const orientationType = screen.orientation.type;
+      const orientationAngle = screen.orientation.angle;
+      
+      // Landscape device with portrait dimensions
+      if (orientationType.includes('landscape') && width < height) {
+        anomalies.push('orientation-dimension-mismatch');
+        confidence = Math.max(confidence, 0.4);
+      }
+      
+      // Portrait device with landscape dimensions
+      if (orientationType.includes('portrait') && width > height) {
+        anomalies.push('orientation-dimension-mismatch');
+        confidence = Math.max(confidence, 0.4);
+      }
+    }
+
+    // Check for innerWidth/Height being exactly equal to outer (no browser chrome)
+    if (innerWidth === outerWidth && innerHeight === outerHeight && 
+        outerWidth > 0 && outerHeight > 0) {
+      anomalies.push('no-browser-chrome');
+      confidence = Math.max(confidence, 0.5);
+    }
+
+    const triggered = anomalies.length > 0;
+
+    return this.createResult(triggered, {
+      anomalies,
+      dimensions: {
+        screen: { width, height },
+        available: { width: availWidth, height: availHeight },
+        window: { outer: { width: outerWidth, height: outerHeight }, 
+                  inner: { width: innerWidth, height: innerHeight } },
+        colorDepth,
+        devicePixelRatio: dpr,
+      },
+    }, confidence);
+  }
+}
+
+export { ScreenSignal };