@axeptio/behavior-detection 1.0.3 → 1.1.1

package/dist/esm/strategies/mouse.d.ts

@@ -2,8 +2,27 @@
  * Mouse Movement Detection Strategy
  * Autonomous module that manages its own mouse event listeners and state
  * Tracks distance and angle to detect unnatural jumps and sharp turns
+ *
+ * Enhanced detection:
+ * - Pre-click stillness (micro-movements before clicks)
+ * - Entry point analysis (where mouse enters viewport)
+ * - Velocity consistency
  */
 import { BaseStrategy, type TimeSeriesPoint } from '../strategy.js';
+interface MousePosition {
+    x: number;
+    y: number;
+    timestamp: number;
+}
+interface EntryPoint {
+    x: number;
+    y: number;
+    timestamp: number;
+    /** Distance from nearest edge (0 = at edge) */
+    edgeDistance: number;
+    /** Which edge: 'top' | 'bottom' | 'left' | 'right' | 'corner' | 'center' */
+    entryEdge: 'top' | 'bottom' | 'left' | 'right' | 'corner' | 'center';
+}
 export declare class MouseStrategy extends BaseStrategy {
     readonly name = "mouse";
     readonly defaultWeight = 0.3;
@@ -15,8 +34,15 @@ export declare class MouseStrategy extends BaseStrategy {
     private rollingWindowMs;
     private listener;
     private leaveListener;
+    private enterListener;
     private isActive;
     private screenDiagonal;
+    /** Entry points tracking */
+    private entryPoints;
+    /** Micro-movements in last 500ms (for stillness detection) */
+    private microMovements;
+    /** Stillness window in ms */
+    private readonly STILLNESS_WINDOW;
     constructor(options?: {
         rollingWindow?: number;
     });
@@ -26,14 +52,40 @@ export declare class MouseStrategy extends BaseStrategy {
     score(): number | undefined;
     /**
      * Mouse-specific pattern detection
-     * Detects bot-like patterns: constant velocity, linear paths
+     * Detects bot-like patterns: constant velocity, linear paths, suspicious entry points
      */
     private detectMousePatterns;
+    /**
+     * Score based on viewport entry points
+     * Humans enter from edges with momentum; bots often start at (0,0) or center
+     */
+    private scoreEntryPoints;
+    /**
+     * Score based on micro-movements (tremor detection)
+     * Humans have natural hand tremor causing 1-5px jitter
+     * Bots have perfect stillness or no micro-movements
+     */
+    private scoreMicroMovements;
+    /**
+     * Get micro-movement count for external use (e.g., by ClickStrategy)
+     */
+    getMicroMovementCount(): number;
+    /**
+     * Get last position for external use
+     */
+    getLastPosition(): {
+        x: number;
+        y: number;
+    } | null;
     getDebugInfo(): {
         eventCount: number;
         rollingWindow: number;
         isActive: boolean;
         distanceSeries: TimeSeriesPoint[];
         angleSeries: TimeSeriesPoint[];
+        entryPoints: EntryPoint[];
+        microMovementCount: number;
+        lastPosition: MousePosition | null;
     };
 }
+export {};

package/dist/esm/strategies/mouse.js

@@ -2,6 +2,11 @@
  * Mouse Movement Detection Strategy
  * Autonomous module that manages its own mouse event listeners and state
  * Tracks distance and angle to detect unnatural jumps and sharp turns
+ *
+ * Enhanced detection:
+ * - Pre-click stillness (micro-movements before clicks)
+ * - Entry point analysis (where mouse enters viewport)
+ * - Velocity consistency
  */
 import { BaseStrategy } from '../strategy.js';
 import { calculateStatistics, gaussian } from '../math-utils.js';
@@ -18,8 +23,15 @@ export class MouseStrategy extends BaseStrategy {
         this.rollingWindowMs = 5000;
         this.listener = null;
         this.leaveListener = null;
+        this.enterListener = null;
         this.isActive = false;
         this.screenDiagonal = 1;
+        /** Entry points tracking */
+        this.entryPoints = [];
+        /** Micro-movements in last 500ms (for stillness detection) */
+        this.microMovements = [];
+        /** Stillness window in ms */
+        this.STILLNESS_WINDOW = 500;
         if ((options === null || options === void 0 ? void 0 : options.rollingWindow) !== undefined)
             this.rollingWindowMs = options.rollingWindow;
     }
@@ -34,12 +46,21 @@ export class MouseStrategy extends BaseStrategy {
         this.listener = (e) => {
             const mouseEvent = e;
             const now = Date.now();
-            const currentPos = { x: mouseEvent.clientX, y: mouseEvent.clientY };
+            const currentPos = { x: mouseEvent.clientX, y: mouseEvent.clientY, timestamp: now };
             // Calculate distance and angle from previous position
             if (this.lastPosition) {
                 const dx = currentPos.x - this.lastPosition.x;
                 const dy = currentPos.y - this.lastPosition.y;
                 const pixelDistance = Math.sqrt(dx * dx + dy * dy);
+                // Track micro-movements (1-5px) for stillness detection
+                if (pixelDistance >= 1 && pixelDistance <= 5) {
+                    this.microMovements.push({ dx, dy, timestamp: now });
+                    // Clean up old micro-movements (shift from front, more efficient than filter)
+                    const cutoffMicro = now - this.STILLNESS_WINDOW;
+                    while (this.microMovements.length > 0 && this.microMovements[0].timestamp < cutoffMicro) {
+                        this.microMovements.shift();
+                    }
+                }
                 // Normalize distance to screen diagonal (0-1 range)
                 // A full diagonal movement = 1.0, a 10px movement on 2000px screen = 0.005
                 const normalizedDistance = pixelDistance / this.screenDiagonal;
@@ -72,6 +93,67 @@ export class MouseStrategy extends BaseStrategy {
             this.lastPosition = currentPos;
         };
         document.addEventListener('mousemove', this.listener, { passive: true });
+        // Track mouse entry points into viewport
+        this.enterListener = (e) => {
+            const mouseEvent = e;
+            const now = Date.now();
+            const x = mouseEvent.clientX;
+            const y = mouseEvent.clientY;
+            const width = window.innerWidth;
+            const height = window.innerHeight;
+            // Calculate edge distances
+            const distTop = y;
+            const distBottom = height - y;
+            const distLeft = x;
+            const distRight = width - x;
+            const minEdgeDist = Math.min(distTop, distBottom, distLeft, distRight);
+            // Determine entry edge
+            let entryEdge;
+            const edgeThreshold = 50; // pixels from edge to count as edge entry
+            if (minEdgeDist < edgeThreshold) {
+                if (distTop <= minEdgeDist)
+                    entryEdge = 'top';
+                else if (distBottom <= minEdgeDist)
+                    entryEdge = 'bottom';
+                else if (distLeft <= minEdgeDist)
+                    entryEdge = 'left';
+                else
+                    entryEdge = 'right';
+            }
+            else if (x > width * 0.35 && x < width * 0.65 &&
+                y > height * 0.35 && y < height * 0.65) {
+                entryEdge = 'center'; // Suspicious - bots often start at center
+            }
+            else if ((distTop < edgeThreshold * 2 && distLeft < edgeThreshold * 2) ||
+                (distTop < edgeThreshold * 2 && distRight < edgeThreshold * 2) ||
+                (distBottom < edgeThreshold * 2 && distLeft < edgeThreshold * 2) ||
+                (distBottom < edgeThreshold * 2 && distRight < edgeThreshold * 2)) {
+                entryEdge = 'corner';
+            }
+            else {
+                // Entry from middle of an edge, normal
+                if (distTop < distBottom && distTop < distLeft && distTop < distRight)
+                    entryEdge = 'top';
+                else if (distBottom < distLeft && distBottom < distRight)
+                    entryEdge = 'bottom';
+                else if (distLeft < distRight)
+                    entryEdge = 'left';
+                else
+                    entryEdge = 'right';
+            }
+            this.entryPoints.push({
+                x,
+                y,
+                timestamp: now,
+                edgeDistance: minEdgeDist,
+                entryEdge,
+            });
+            // Keep only last 20 entry points (shift is more memory efficient than slice)
+            if (this.entryPoints.length > 20) {
+                this.entryPoints.shift();
+            }
+        };
+        document.addEventListener('mouseenter', this.enterListener, { passive: true });
         // Clear data when mouse leaves the window (discontinuous tracking)
         this.leaveListener = () => {
             this.distanceSeries = [];
@@ -79,6 +161,7 @@ export class MouseStrategy extends BaseStrategy {
             this.lastPosition = null;
             this.lastAngle = 0;
             this.cumulativeAngle = 0;
+            this.microMovements = [];
         };
         document.addEventListener('mouseleave', this.leaveListener, { passive: true });
     }
@@ -94,6 +177,10 @@ export class MouseStrategy extends BaseStrategy {
             document.removeEventListener('mouseleave', this.leaveListener);
             this.leaveListener = null;
         }
+        if (this.enterListener) {
+            document.removeEventListener('mouseenter', this.enterListener);
+            this.enterListener = null;
+        }
     }
     reset() {
         this.distanceSeries = [];
@@ -101,6 +188,8 @@ export class MouseStrategy extends BaseStrategy {
         this.lastPosition = null;
         this.lastAngle = 0;
         this.cumulativeAngle = 0;
+        this.entryPoints = [];
+        this.microMovements = [];
     }
     score() {
         if (this.distanceSeries.length < 10)
@@ -111,7 +200,7 @@ export class MouseStrategy extends BaseStrategy {
     }
     /**
      * Mouse-specific pattern detection
-     * Detects bot-like patterns: constant velocity, linear paths
+     * Detects bot-like patterns: constant velocity, linear paths, suspicious entry points
      */
     detectMousePatterns() {
         if (this.distanceSeries.length < 10)
@@ -141,8 +230,112 @@ export class MouseStrategy extends BaseStrategy {
             score += gaussian(avgChange, 0.15, 0.12);
             factors++;
         }
+        // 3. ENTRY POINT ANALYSIS - Where does mouse enter the viewport?
+        const entryScore = this.scoreEntryPoints();
+        if (entryScore !== undefined) {
+            score += entryScore;
+            factors++;
+        }
+        // 4. MICRO-MOVEMENT PRESENCE - Humans have tremors, bots don't
+        const microScore = this.scoreMicroMovements();
+        if (microScore !== undefined) {
+            score += microScore;
+            factors++;
+        }
         return factors > 0 ? score / factors : undefined;
     }
+    /**
+     * Score based on viewport entry points
+     * Humans enter from edges with momentum; bots often start at (0,0) or center
+     */
+    scoreEntryPoints() {
+        if (this.entryPoints.length < 2)
+            return undefined;
+        let suspiciousCount = 0;
+        let centerCount = 0;
+        let cornerCount = 0;
+        let originCount = 0;
+        for (const entry of this.entryPoints) {
+            // Check for (0,0) or near-origin entries (very suspicious)
+            if (entry.x < 5 && entry.y < 5) {
+                originCount++;
+                suspiciousCount++;
+            }
+            else if (entry.entryEdge === 'center') {
+                centerCount++;
+                suspiciousCount++;
+            }
+            else if (entry.entryEdge === 'corner') {
+                cornerCount++;
+                // Corners are slightly suspicious but not as bad as center
+                if (entry.edgeDistance < 10)
+                    suspiciousCount++;
+            }
+        }
+        const total = this.entryPoints.length;
+        const suspiciousRatio = suspiciousCount / total;
+        // High ratio of origin entries = definitely bot
+        if (originCount >= 2 || originCount / total >= 0.5)
+            return 0.1;
+        // High ratio of center entries = likely bot
+        if (centerCount / total >= 0.5)
+            return 0.2;
+        // Mix of suspicious entries
+        if (suspiciousRatio >= 0.7)
+            return 0.3;
+        if (suspiciousRatio >= 0.5)
+            return 0.5;
+        if (suspiciousRatio >= 0.3)
+            return 0.7;
+        // Mostly edge entries = human
+        return 1.0;
+    }
+    /**
+     * Score based on micro-movements (tremor detection)
+     * Humans have natural hand tremor causing 1-5px jitter
+     * Bots have perfect stillness or no micro-movements
+     */
+    scoreMicroMovements() {
+        // Need some movement data first
+        if (this.distanceSeries.length < 20)
+            return undefined;
+        const microCount = this.microMovements.length;
+        // Calculate expected micro-movements based on tracking duration
+        // Humans should have ~5-20 micro-movements per second when cursor is active
+        const oldestEvent = this.distanceSeries[0];
+        const newestEvent = this.distanceSeries[this.distanceSeries.length - 1];
+        const durationMs = newestEvent.timestamp - oldestEvent.timestamp;
+        if (durationMs < 1000)
+            return undefined; // Need at least 1 second of data
+        // Micro-movements per second
+        const microPerSecond = (microCount / durationMs) * 1000;
+        // No micro-movements at all = very suspicious
+        if (microCount === 0)
+            return 0.3;
+        // Very few micro-movements = somewhat suspicious
+        if (microPerSecond < 1)
+            return 0.5;
+        // Some micro-movements = more human-like
+        if (microPerSecond < 5)
+            return 0.7;
+        // Good amount of micro-movements = human
+        if (microPerSecond >= 5 && microPerSecond <= 30)
+            return 1.0;
+        // Excessive micro-movements (> 30/sec) might be artificial noise
+        return 0.8;
+    }
+    /**
+     * Get micro-movement count for external use (e.g., by ClickStrategy)
+     */
+    getMicroMovementCount() {
+        return this.microMovements.length;
+    }
+    /**
+     * Get last position for external use
+     */
+    getLastPosition() {
+        return this.lastPosition ? { x: this.lastPosition.x, y: this.lastPosition.y } : null;
+    }
     getDebugInfo() {
         return {
             eventCount: this.distanceSeries.length,
@@ -150,6 +343,9 @@ export class MouseStrategy extends BaseStrategy {
             isActive: this.isActive,
             distanceSeries: this.distanceSeries,
             angleSeries: this.angleSeries,
+            entryPoints: this.entryPoints,
+            microMovementCount: this.microMovements.length,
+            lastPosition: this.lastPosition,
         };
     }
 }

package/dist/esm/strategies/timing.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Timing Analysis Strategy
+ * Detects bot-like timing patterns in user interactions
+ *
+ * Key detection signals:
+ * - Pre-action stillness (humans have micro-movements before clicking)
+ * - Action timing patterns (machine-precise intervals)
+ * - Inactivity patterns (bursts after long silence, no idle variance)
+ * - Actions while tab is hidden (bots ignore visibility)
+ */
+import { BaseStrategy } from '../strategy.js';
+export declare class TimingStrategy extends BaseStrategy {
+    readonly name = "timing";
+    readonly defaultWeight = 0.15;
+    private actions;
+    private mouseStillness;
+    private microMovements;
+    private isActive;
+    private mouseListener;
+    private clickListener;
+    private keydownListener;
+    private scrollListener;
+    /** Time window to consider for pre-action stillness (ms) */
+    private readonly STILLNESS_WINDOW;
+    /** Minimum distance to count as meaningful movement (px) */
+    private readonly MICRO_MOVEMENT_THRESHOLD;
+    /** Maximum micro-movement to count (jitter vs intentional) (px) */
+    private readonly MAX_MICRO_MOVEMENT;
+    /** Machine-precision threshold (intervals within this are suspicious) */
+    private readonly MACHINE_PRECISION_THRESHOLD;
+    start(): void;
+    private recordAction;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    /**
+     * Score based on pre-action stillness
+     * Humans have micro-movements before clicking; bots are perfectly still
+     */
+    private scorePreActionStillness;
+    /**
+     * Score mouse-to-click delay patterns (using pre-filtered cache)
+     */
+    private scoreMouseToClickDelayFromCache;
+    /**
+     * Score action intervals for machine-like precision
+     * Detects exact intervals: 100ms, 500ms, 1000ms
+     */
+    private scoreActionIntervals;
+    /**
+     * Score based on actions while document was hidden (using pre-computed count)
+     */
+    private scoreHiddenActionsFromCount;
+    getDebugInfo(): {
+        actionCount: number;
+        clickCount: number;
+        keydownCount: number;
+        scrollCount: number;
+        hiddenActionCount: number;
+        microMovementCount: number;
+        intervals: number[];
+        lastStillnessDuration: number | null;
+    };
+}