@axeptio/behavior-detection 1.0.0

package/dist/cjs/strategies/scroll.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Scroll Behavior Detection Strategy
+ * Autonomous module managing scroll event listeners
+ * Tracks normalized scroll distance and velocity patterns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScrollStrategy = void 0;
+const strategy_1 = require("../strategy");
+const math_utils_1 = require("../math-utils");
+class ScrollStrategy extends strategy_1.BaseStrategy {
+    constructor(options) {
+        super();
+        this.name = 'scroll';
+        this.defaultWeight = 0.15;
+        this.distanceSeries = [];
+        this.velocitySeries = [];
+        this.lastScrollY = null;
+        this.lastTimestamp = 0;
+        this.rollingWindowMs = 5000;
+        this.documentHeight = 1;
+        this.listener = null;
+        this.isActive = false;
+        if ((options === null || options === void 0 ? void 0 : options.rollingWindow) !== undefined)
+            this.rollingWindowMs = options.rollingWindow;
+    }
+    start() {
+        if (this.isActive)
+            return;
+        this.isActive = true;
+        // Calculate document height for normalization
+        this.documentHeight = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight, 1);
+        this.listener = (_e) => {
+            const scrollY = window.scrollY;
+            const now = Date.now();
+            // Always update last position on first event
+            if (this.lastScrollY === null) {
+                this.lastScrollY = scrollY;
+                this.lastTimestamp = now;
+                return;
+            }
+            const pixelDelta = scrollY - this.lastScrollY;
+            const deltaTime = now - this.lastTimestamp;
+            // Skip if no actual scroll happened
+            if (pixelDelta === 0) {
+                return;
+            }
+            // Normalize scroll distance to document height (0-1 range)
+            const normalizedDistance = Math.abs(pixelDelta) / this.documentHeight;
+            // Record all scroll movements (no threshold - let pattern detection decide)
+            if (deltaTime > 0) {
+                const velocity = normalizedDistance / deltaTime; // normalized units per ms
+                // Store as time series
+                this.distanceSeries.push({ value: normalizedDistance, timestamp: now });
+                this.velocitySeries.push({ value: velocity, timestamp: now });
+                // Notify detector for confidence tracking
+                this.notifyEvent(Math.min(1, normalizedDistance * 10));
+                // Apply rolling window efficiently
+                const cutoff = now - this.rollingWindowMs;
+                while (this.distanceSeries.length > 0 && this.distanceSeries[0].timestamp < cutoff) {
+                    this.distanceSeries.shift();
+                    this.velocitySeries.shift();
+                }
+            }
+            this.lastScrollY = scrollY;
+            this.lastTimestamp = now;
+        };
+        // Listen on window for scroll events (document scrolling)
+        window.addEventListener('scroll', this.listener, { passive: true });
+    }
+    stop() {
+        if (!this.isActive)
+            return;
+        this.isActive = false;
+        if (this.listener) {
+            window.removeEventListener('scroll', this.listener);
+            this.listener = null;
+        }
+    }
+    reset() {
+        this.distanceSeries = [];
+        this.velocitySeries = [];
+        this.lastScrollY = null;
+        this.lastTimestamp = 0;
+    }
+    score() {
+        if (this.distanceSeries.length < 2)
+            return undefined;
+        // Scroll-specific pattern detection
+        return this.detectScrollPatterns();
+    }
+    /**
+     * Scroll-specific pattern detection
+     * Detects bot-like patterns: constant deltas, instant jumps, too smooth
+     */
+    detectScrollPatterns() {
+        if (this.distanceSeries.length < 2)
+            return undefined;
+        let score = 0;
+        let factors = 0;
+        // 1. IDENTICAL DELTAS - Smoking gun for bots
+        const distances = this.distanceSeries.map(p => p.value);
+        if (distances.length >= 2) {
+            // Check if all distances are identical (tolerance for floating point)
+            const uniqueDistances = new Set(distances.map(d => Math.round(d * 1000))).size;
+            if (uniqueDistances === 1) {
+                // All scroll amounts identical = definite bot
+                return 0.05;
+            }
+        }
+        // 2. DISTANCE CONSISTENCY - Bots often scroll same amount repeatedly
+        if (distances.length >= 2) {
+            const stats = (0, math_utils_1.calculateStatistics)(distances);
+            // Real humans have high CV (>0.8) due to natural scroll acceleration/deceleration
+            // Simple automation has lower CV even with varied amounts
+            // Gaussian centered high with narrow width - be strict
+            score += (0, math_utils_1.gaussian)(stats.cv, 1.0, 0.4);
+            factors++;
+        }
+        // 3. VELOCITY VARIATION - Humans have highly variable scroll speeds
+        const velocities = this.velocitySeries.map(p => p.value);
+        if (velocities.length >= 2) {
+            const stats = (0, math_utils_1.calculateStatistics)(velocities);
+            // Human velocity is very chaotic (acceleration/deceleration)
+            // Automation has more consistent velocity even with delays
+            score += (0, math_utils_1.gaussian)(stats.cv, 1.2, 0.5);
+            factors++;
+        }
+        // 4. INSTANT JUMPS - Detect programmatic scrollTo
+        const instantJumps = distances.filter(d => d > 0.1).length; // >10% of document in one event
+        if (distances.length > 0) {
+            const jumpRatio = instantJumps / distances.length;
+            // Penalize high jump ratio (programmatic scrollTo)
+            score += (0, math_utils_1.inverseSigmoid)(jumpRatio, 0.3, 15);
+            factors++;
+        }
+        return factors > 0 ? score / factors : undefined;
+    }
+    getDebugInfo() {
+        return {
+            eventCount: this.distanceSeries.length,
+            rollingWindow: this.rollingWindowMs,
+            isActive: this.isActive,
+            distanceSeries: this.distanceSeries,
+            velocitySeries: this.velocitySeries,
+        };
+    }
+}
+exports.ScrollStrategy = ScrollStrategy;

package/dist/cjs/strategies/tap.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tap Behavior Detection Strategy (Mobile)
+ * Monitors touch interactions on specific elements
+ * Analyzes tap duration, precision, movement, and timing patterns
+ */
+import { BaseStrategy } from '../strategy';
+export declare class TapStrategy extends BaseStrategy {
+    readonly name = "tap";
+    readonly defaultWeight = 0.35;
+    private events;
+    private targetSelectors;
+    private touchStartListeners;
+    private touchEndListeners;
+    private activeTouches;
+    private isActive;
+    constructor(options?: {
+        targetSelectors?: string[];
+    });
+    start(): void;
+    addTarget(selector: string): void;
+    private attachTouchListeners;
+    private attachTouchListenersForSelector;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    getDebugInfo(): {
+        eventCount: number;
+        positions: {
+            outside: number;
+            deadCenter: number;
+            overElement: number;
+        };
+        durations: number[];
+        movements: number[];
+        inViewport: number;
+        trackedElements: number;
+    };
+}

package/dist/cjs/strategies/tap.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Tap Behavior Detection Strategy (Mobile)
+ * Monitors touch interactions on specific elements
+ * Analyzes tap duration, precision, movement, and timing patterns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TapStrategy = void 0;
+const strategy_1 = require("../strategy");
+const math_utils_1 = require("../math-utils");
+class TapStrategy extends strategy_1.BaseStrategy {
+    constructor(options) {
+        super();
+        this.name = 'tap';
+        this.defaultWeight = 0.35;
+        this.events = [];
+        this.targetSelectors = ['button', 'a', 'input[type="submit"]', '[role="button"]'];
+        this.touchStartListeners = new Map();
+        this.touchEndListeners = new Map();
+        this.activeTouches = new Map();
+        this.isActive = false;
+        if (options === null || options === void 0 ? void 0 : options.targetSelectors) {
+            this.targetSelectors = options.targetSelectors;
+        }
+    }
+    start() {
+        if (this.isActive)
+            return;
+        this.isActive = true;
+        this.attachTouchListeners();
+    }
+    addTarget(selector) {
+        if (!this.targetSelectors.includes(selector)) {
+            this.targetSelectors.push(selector);
+            if (this.isActive) {
+                this.attachTouchListenersForSelector(selector);
+            }
+        }
+    }
+    attachTouchListeners() {
+        this.targetSelectors.forEach(selector => {
+            this.attachTouchListenersForSelector(selector);
+        });
+    }
+    attachTouchListenersForSelector(selector) {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach(element => {
+            if (this.touchStartListeners.has(element))
+                return;
+            const startListener = (e) => {
+                const touchEvent = e;
+                // Only track first touch (ignore multi-touch)
+                if (touchEvent.touches.length !== 1)
+                    return;
+                const touch = touchEvent.touches[0];
+                this.activeTouches.set(touch.identifier, {
+                    x: touch.clientX,
+                    y: touch.clientY,
+                    timestamp: Date.now(),
+                    element,
+                });
+            };
+            const endListener = (e) => {
+                const touchEvent = e;
+                if (touchEvent.changedTouches.length !== 1)
+                    return;
+                const touch = touchEvent.changedTouches[0];
+                const startData = this.activeTouches.get(touch.identifier);
+                if (!startData || startData.element !== element)
+                    return;
+                const now = Date.now();
+                const duration = now - startData.timestamp;
+                const dx = touch.clientX - startData.x;
+                const dy = touch.clientY - startData.y;
+                const movement = Math.sqrt(dx * dx + dy * dy);
+                const rect = element.getBoundingClientRect();
+                const inViewport = (rect.top >= 0 &&
+                    rect.left >= 0 &&
+                    rect.bottom <= window.innerHeight &&
+                    rect.right <= window.innerWidth);
+                // Analyze tap position
+                const tx = touch.clientX;
+                const ty = touch.clientY;
+                const overElement = (tx >= rect.left &&
+                    tx <= rect.right &&
+                    ty >= rect.top &&
+                    ty <= rect.bottom);
+                let position;
+                if (!overElement) {
+                    position = 'outside';
+                }
+                else {
+                    const centerX = rect.left + rect.width / 2;
+                    const centerY = rect.top + rect.height / 2;
+                    const distanceFromCenter = Math.sqrt((tx - centerX) ** 2 + (ty - centerY) ** 2);
+                    // Dead center = within 2px
+                    position = distanceFromCenter < 2 ? 'dead-center' : 'over-element';
+                }
+                this.events.push({
+                    x: tx,
+                    y: ty,
+                    rect,
+                    inViewport,
+                    position,
+                    duration,
+                    movement,
+                    timestamp: now,
+                });
+                // Notify detector - taps are high-value events
+                this.notifyEvent(1.0);
+                this.activeTouches.delete(touch.identifier);
+            };
+            element.addEventListener('touchstart', startListener, { passive: true });
+            element.addEventListener('touchend', endListener, { passive: true });
+            this.touchStartListeners.set(element, startListener);
+            this.touchEndListeners.set(element, endListener);
+        });
+    }
+    stop() {
+        if (!this.isActive)
+            return;
+        this.isActive = false;
+        this.touchStartListeners.forEach((listener, element) => {
+            element.removeEventListener('touchstart', listener);
+        });
+        this.touchStartListeners.clear();
+        this.touchEndListeners.forEach((listener, element) => {
+            element.removeEventListener('touchend', listener);
+        });
+        this.touchEndListeners.clear();
+        this.activeTouches.clear();
+    }
+    reset() {
+        this.events = [];
+        this.activeTouches.clear();
+    }
+    score() {
+        if (this.events.length === 0)
+            return undefined;
+        let score = 0;
+        let factors = 0;
+        // 1. Position accuracy
+        let positionScore = 0;
+        for (const tap of this.events) {
+            switch (tap.position) {
+                case 'outside':
+                    positionScore += 0.0; // Bot
+                    break;
+                case 'dead-center':
+                    positionScore += 0.5; // Suspicious
+                    break;
+                case 'over-element':
+                    positionScore += 1.0; // Human
+                    break;
+            }
+        }
+        score += positionScore / this.events.length;
+        factors++;
+        // 2. Tap duration variation - Humans have natural variation (50-150ms typical)
+        const durations = this.events.map(e => e.duration);
+        if (durations.length >= 2) {
+            const durationAnalysis = (0, math_utils_1.analyzeIntervals)(durations);
+            if (durationAnalysis) {
+                const { statistics, allIdentical } = durationAnalysis;
+                // All identical = bot
+                if (allIdentical) {
+                    return 0.05;
+                }
+                // Human tap durations have moderate CV (~0.3-0.5)
+                score += (0, math_utils_1.scoreCoefficientOfVariation)(statistics.cv);
+                factors++;
+                // Ideal duration: 70-120ms
+                score += (0, math_utils_1.gaussian)(statistics.mean, 95, 40);
+                factors++;
+            }
+        }
+        // 3. Tap movement - Real fingers move slightly (1-5px), bots are often 0px
+        const movements = this.events.map(e => e.movement);
+        if (movements.length > 0) {
+            const avgMovement = movements.reduce((a, b) => a + b, 0) / movements.length;
+            // Some movement is natural (1-5px), too much is a swipe, zero is suspicious
+            score += (0, math_utils_1.gaussian)(avgMovement, 2, 3);
+            factors++;
+        }
+        // 4. Tap interval timing - Time between taps should vary naturally
+        if (this.events.length >= 3) {
+            const intervals = [];
+            for (let i = 1; i < this.events.length; i++) {
+                intervals.push(this.events[i].timestamp - this.events[i - 1].timestamp);
+            }
+            const intervalAnalysis = (0, math_utils_1.analyzeIntervals)(intervals);
+            if (intervalAnalysis && !intervalAnalysis.allIdentical) {
+                score += (0, math_utils_1.scoreCoefficientOfVariation)(intervalAnalysis.statistics.cv);
+                factors++;
+            }
+        }
+        return factors > 0 ? score / factors : undefined;
+    }
+    getDebugInfo() {
+        return {
+            eventCount: this.events.length,
+            positions: {
+                outside: this.events.filter(e => e.position === 'outside').length,
+                deadCenter: this.events.filter(e => e.position === 'dead-center').length,
+                overElement: this.events.filter(e => e.position === 'over-element').length,
+            },
+            durations: this.events.map(e => e.duration),
+            movements: this.events.map(e => e.movement),
+            inViewport: this.events.filter(e => e.inViewport).length,
+            trackedElements: this.touchStartListeners.size,
+        };
+    }
+}
+exports.TapStrategy = TapStrategy;

package/dist/cjs/strategy.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Detection Strategy Interface
+ * Each strategy is a fully autonomous module responsible for:
+ * - Registering its own event listeners
+ * - Managing its own state and events
+ * - Responding to lifecycle events (start/stop)
+ * - Optionally receiving tick updates for polling-based detection
+ */
+/**
+ * Time series data point
+ * Used by strategies that track values over time
+ */
+export interface TimeSeriesPoint {
+    value: number;
+    timestamp: number;
+}
+/**
+ * Event notification from strategy to detector
+ */
+export interface StrategyEvent {
+    strategy: string;
+    weight: number;
+    timestamp: number;
+}
+/**
+ * Base class for detection strategies
+ * Handles event callback pattern to avoid repetition
+ */
+export declare abstract class BaseStrategy implements DetectionStrategy {
+    abstract readonly name: string;
+    abstract readonly defaultWeight: number;
+    protected eventCallback: ((event: StrategyEvent) => void) | null;
+    setEventCallback(callback: (event: StrategyEvent) => void): void;
+    protected notifyEvent(weight: number): void;
+    abstract start(): void;
+    abstract stop(): void;
+    abstract reset(): void;
+    abstract score(): number | undefined;
+    onTick?(timestamp: number): void;
+    getDebugInfo?(): any;
+}
+export interface DetectionStrategy {
+    /**
+     * Unique identifier for this strategy
+     */
+    readonly name: string;
+    /**
+     * Default weight for this strategy in overall score calculation
+     */
+    readonly defaultWeight: number;
+    /**
+     * Start detection - register event listeners
+     */
+    start(): void;
+    /**
+     * Stop detection - remove event listeners, cleanup
+     */
+    stop(): void;
+    /**
+     * Reset collected data
+     */
+    reset(): void;
+    /**
+     * Calculate score based on collected data
+     * @returns Score 0-1, or undefined if insufficient data
+     */
+    score(): number | undefined;
+    /**
+     * Optional: Called on regular interval for polling-based detection
+     * Use this to sample document/window/navigator state
+     * @param timestamp - Current timestamp
+     */
+    onTick?(timestamp: number): void;
+    /**
+     * Optional: Get debug information about collected data
+     */
+    getDebugInfo?(): any;
+    /**
+     * Optional: Set callback for when events are received
+     * Used to track confidence - detector will be notified when strategy receives data
+     * @param callback - Function to call when event is received
+     */
+    setEventCallback?(callback: (event: StrategyEvent) => void): void;
+}
+export interface StrategyConfig {
+    strategy: DetectionStrategy;
+    weight: number;
+    enabled: boolean;
+}
+export interface TickOptions {
+    /**
+     * Tick interval in milliseconds
+     * Default: 1000 (1 second)
+     */
+    interval?: number;
+    /**
+     * Whether to start ticking immediately
+     * Default: false (start with detector.start())
+     */
+    autoStart?: boolean;
+    /**
+     * Automatically pause detection when the tab is hidden
+     * Uses the Page Visibility API to stop strategies and tick when document.hidden is true
+     * Default: true (recommended for better performance and battery life)
+     */
+    pauseOnHidden?: boolean;
+}

package/dist/cjs/strategy.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Detection Strategy Interface
+ * Each strategy is a fully autonomous module responsible for:
+ * - Registering its own event listeners
+ * - Managing its own state and events
+ * - Responding to lifecycle events (start/stop)
+ * - Optionally receiving tick updates for polling-based detection
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseStrategy = void 0;
+/**
+ * Base class for detection strategies
+ * Handles event callback pattern to avoid repetition
+ */
+class BaseStrategy {
+    constructor() {
+        this.eventCallback = null;
+    }
+    setEventCallback(callback) {
+        this.eventCallback = callback;
+    }
+    notifyEvent(weight) {
+        if (this.eventCallback) {
+            this.eventCallback({
+                strategy: this.name,
+                weight,
+                timestamp: Date.now()
+            });
+        }
+    }
+}
+exports.BaseStrategy = BaseStrategy;