@axeptio/behavior-detection 1.0.0

package/dist/cjs/math-utils.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Mathematical utility functions for continuous scoring
+ * Replaces magic number if-else chains with smooth mathematical functions
+ */
+/**
+ * Sigmoid function - Maps any value to [0, 1] with smooth S-curve
+ * @param x - Input value
+ * @param midpoint - Value that maps to 0.5
+ * @param steepness - How steep the curve is (higher = steeper)
+ */
+export declare function sigmoid(x: number, midpoint?: number, steepness?: number): number;
+/**
+ * Inverse sigmoid - High values map to low scores
+ */
+export declare function inverseSigmoid(x: number, midpoint?: number, steepness?: number): number;
+/**
+ * Gaussian (bell curve) - Peak at ideal value, falls off on both sides
+ * @param x - Input value
+ * @param ideal - Optimal value (peak of curve)
+ * @param width - How wide the acceptable range is
+ */
+export declare function gaussian(x: number, ideal?: number, width?: number): number;
+/**
+ * Exponential decay - High values get penalized exponentially
+ */
+export declare function exponentialDecay(x: number, decayRate?: number): number;
+/**
+ * Normalize value to [0, 1] range
+ */
+export declare function normalize(value: number, min?: number, max?: number): number;
+/**
+ * Clamp value to [0, 1]
+ */
+export declare function clamp01(value: number): number;
+/**
+ * Statistical metrics for an array of numbers
+ */
+export interface Statistics {
+    mean: number;
+    variance: number;
+    stdDev: number;
+    cv: number;
+}
+/**
+ * Calculate statistical metrics for an array of numbers
+ * @param values - Array of numerical values
+ * @returns Statistical metrics (mean, variance, stdDev, cv)
+ */
+export declare function calculateStatistics(values: number[]): Statistics;
+/**
+ * Analysis result for interval patterns
+ */
+export interface IntervalAnalysis {
+    statistics: Statistics;
+    uniqueCount: number;
+    allIdentical: boolean;
+}
+/**
+ * Analyze timing intervals for bot-like patterns
+ * Returns raw analysis data without scoring - caller decides heuristics
+ *
+ * @param intervals - Array of time intervals (ms)
+ * @returns Analysis of interval patterns including stats and uniqueness
+ */
+export declare function analyzeIntervals(intervals: number[]): IntervalAnalysis | undefined;
+/**
+ * Score coefficient of variation
+ * Maps CV to human-likeness score using Gaussian
+ * Ideal CV is around 0.4-0.5 (moderate variation)
+ */
+export declare function scoreCoefficientOfVariation(cv: number): number;
+/**
+ * Score entropy - Higher is better (more random = more human)
+ * Uses sigmoid to smoothly map entropy to score
+ */
+export declare function scoreEntropy(normalizedEntropy: number): number;
+/**
+ * Score autocorrelation - Lower is better (less periodic = more human)
+ */
+export declare function scoreAutocorrelation(autocorr: number): number;
+/**
+ * Score jerk - Lower is better (smoother = more human)
+ */
+export declare function scoreJerk(avgJerk: number): number;

package/dist/cjs/math-utils.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Mathematical utility functions for continuous scoring
+ * Replaces magic number if-else chains with smooth mathematical functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sigmoid = sigmoid;
+exports.inverseSigmoid = inverseSigmoid;
+exports.gaussian = gaussian;
+exports.exponentialDecay = exponentialDecay;
+exports.normalize = normalize;
+exports.clamp01 = clamp01;
+exports.calculateStatistics = calculateStatistics;
+exports.analyzeIntervals = analyzeIntervals;
+exports.scoreCoefficientOfVariation = scoreCoefficientOfVariation;
+exports.scoreEntropy = scoreEntropy;
+exports.scoreAutocorrelation = scoreAutocorrelation;
+exports.scoreJerk = scoreJerk;
+/**
+ * Sigmoid function - Maps any value to [0, 1] with smooth S-curve
+ * @param x - Input value
+ * @param midpoint - Value that maps to 0.5
+ * @param steepness - How steep the curve is (higher = steeper)
+ */
+function sigmoid(x, midpoint = 0, steepness = 1) {
+    return 1 / (1 + Math.exp(-steepness * (x - midpoint)));
+}
+/**
+ * Inverse sigmoid - High values map to low scores
+ */
+function inverseSigmoid(x, midpoint = 0, steepness = 1) {
+    return 1 - sigmoid(x, midpoint, steepness);
+}
+/**
+ * Gaussian (bell curve) - Peak at ideal value, falls off on both sides
+ * @param x - Input value
+ * @param ideal - Optimal value (peak of curve)
+ * @param width - How wide the acceptable range is
+ */
+function gaussian(x, ideal = 0, width = 1) {
+    const exponent = -Math.pow(x - ideal, 2) / (2 * width * width);
+    return Math.exp(exponent);
+}
+/**
+ * Exponential decay - High values get penalized exponentially
+ */
+function exponentialDecay(x, decayRate = 0.1) {
+    return Math.exp(-decayRate * x);
+}
+/**
+ * Normalize value to [0, 1] range
+ */
+function normalize(value, min = 0, max = 1) {
+    if (max === min)
+        return 0.5;
+    return Math.max(0, Math.min(1, (value - min) / (max - min)));
+}
+/**
+ * Clamp value to [0, 1]
+ */
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/**
+ * Calculate statistical metrics for an array of numbers
+ * @param values - Array of numerical values
+ * @returns Statistical metrics (mean, variance, stdDev, cv)
+ */
+function calculateStatistics(values) {
+    if (values.length === 0) {
+        return { mean: 0, variance: 0, stdDev: 0, cv: 0 };
+    }
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+    const stdDev = Math.sqrt(variance);
+    const cv = mean > 0 ? stdDev / mean : 0;
+    return { mean, variance, stdDev, cv };
+}
+/**
+ * Analyze timing intervals for bot-like patterns
+ * Returns raw analysis data without scoring - caller decides heuristics
+ *
+ * @param intervals - Array of time intervals (ms)
+ * @returns Analysis of interval patterns including stats and uniqueness
+ */
+function analyzeIntervals(intervals) {
+    if (intervals.length < 2)
+        return undefined;
+    // Check for identical intervals (round to 10ms to account for floating point)
+    const uniqueCount = new Set(intervals.map(i => Math.round(i / 10))).size;
+    const allIdentical = uniqueCount === 1;
+    // Calculate statistics
+    const statistics = calculateStatistics(intervals);
+    return {
+        statistics,
+        uniqueCount,
+        allIdentical,
+    };
+}
+/**
+ * Score coefficient of variation
+ * Maps CV to human-likeness score using Gaussian
+ * Ideal CV is around 0.4-0.5 (moderate variation)
+ */
+function scoreCoefficientOfVariation(cv) {
+    // Too low (<0.1) = bot-like (too consistent)
+    // Too high (>1.5) = random noise
+    // Ideal = 0.4-0.6 (natural human variation)
+    if (cv < 0.05)
+        return 0.1; // Almost zero variation - definitely bot
+    if (cv > 2.0)
+        return 0.3; // Too random
+    // Gaussian centered at 0.45 with width of 0.35
+    return gaussian(cv, 0.45, 0.35);
+}
+/**
+ * Score entropy - Higher is better (more random = more human)
+ * Uses sigmoid to smoothly map entropy to score
+ */
+function scoreEntropy(normalizedEntropy) {
+    // Entropy of 0.7+ is very human
+    // Entropy < 0.3 is very bot-like
+    return sigmoid(normalizedEntropy, 0.5, 8); // Steep curve at midpoint 0.5
+}
+/**
+ * Score autocorrelation - Lower is better (less periodic = more human)
+ */
+function scoreAutocorrelation(autocorr) {
+    // Low autocorrelation (<0.2) is natural
+    // High autocorrelation (>0.6) is periodic/bot-like
+    return inverseSigmoid(autocorr, 0.4, 10);
+}
+/**
+ * Score jerk - Lower is better (smoother = more human)
+ */
+function scoreJerk(avgJerk) {
+    // Human jerk typically < 0.01
+    // Bot jerk often > 0.1
+    // Use inverse sigmoid
+    return inverseSigmoid(avgJerk, 0.05, 50);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Click Behavior Detection Strategy
+ * Monitors specific elements for click positioning patterns
+ */
+import { BaseStrategy } from '../strategy';
+export declare class ClickStrategy extends BaseStrategy {
+    readonly name = "click";
+    readonly defaultWeight = 0.3;
+    private events;
+    private targetSelectors;
+    private lastMousePosition;
+    private mouseListener;
+    private clickListeners;
+    private isActive;
+    constructor(options?: {
+        targetSelectors?: string[];
+    });
+    start(): void;
+    /**
+     * Add a new target selector at runtime
+     */
+    addTarget(selector: string): void;
+    private attachClickListeners;
+    private attachClickListenersForSelector;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    getDebugInfo(): {
+        eventCount: number;
+        positions: {
+            noMouseData: number;
+            outside: number;
+            deadCenter: number;
+            overElement: number;
+        };
+        inViewport: number;
+        trackedElements: number;
+    };
+}

package/dist/cjs/strategies/click.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Click Behavior Detection Strategy
+ * Monitors specific elements for click positioning patterns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClickStrategy = void 0;
+const strategy_1 = require("../strategy");
+class ClickStrategy extends strategy_1.BaseStrategy {
+    constructor(options) {
+        super();
+        this.name = 'click';
+        this.defaultWeight = 0.30;
+        this.events = [];
+        this.targetSelectors = ['button', 'a', 'input[type="submit"]', '[role="button"]'];
+        this.lastMousePosition = null;
+        this.mouseListener = null;
+        this.clickListeners = 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;
+        // Track mouse position globally
+        this.mouseListener = (e) => {
+            const mouseEvent = e;
+            this.lastMousePosition = {
+                x: mouseEvent.clientX,
+                y: mouseEvent.clientY,
+            };
+        };
+        document.addEventListener('mousemove', this.mouseListener, { passive: true });
+        // Find all matching elements and attach listeners
+        this.attachClickListeners();
+    }
+    /**
+     * Add a new target selector at runtime
+     */
+    addTarget(selector) {
+        if (!this.targetSelectors.includes(selector)) {
+            this.targetSelectors.push(selector);
+            // Attach listeners if already active
+            if (this.isActive) {
+                this.attachClickListenersForSelector(selector);
+            }
+        }
+    }
+    attachClickListeners() {
+        this.targetSelectors.forEach(selector => {
+            this.attachClickListenersForSelector(selector);
+        });
+    }
+    attachClickListenersForSelector(selector) {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach(element => {
+            if (this.clickListeners.has(element))
+                return; // Already attached
+            const listener = (e) => {
+                var _a, _b;
+                const clickEvent = e;
+                const rect = element.getBoundingClientRect();
+                // Check if element is in viewport
+                const inViewport = (rect.top >= 0 &&
+                    rect.left >= 0 &&
+                    rect.bottom <= window.innerHeight &&
+                    rect.right <= window.innerWidth);
+                // Analyze click position
+                let position;
+                if (!this.lastMousePosition) {
+                    position = 'no-mouse-data'; // Bot - no mouse movement
+                }
+                else {
+                    const mx = this.lastMousePosition.x;
+                    const my = this.lastMousePosition.y;
+                    // Check if mouse was over element
+                    const overElement = (mx >= rect.left &&
+                        mx <= rect.right &&
+                        my >= rect.top &&
+                        my <= rect.bottom);
+                    if (!overElement) {
+                        position = 'outside'; // Bot - mouse not over target
+                    }
+                    else {
+                        // Check if dead center (suspicious)
+                        const centerX = rect.left + rect.width / 2;
+                        const centerY = rect.top + rect.height / 2;
+                        const distanceFromCenter = Math.sqrt((mx - centerX) ** 2 + (my - centerY) ** 2);
+                        // Dead center = within 2px of center
+                        if (distanceFromCenter < 2) {
+                            position = 'dead-center'; // Suspicious - too perfect
+                        }
+                        else {
+                            position = 'over-element'; // Human - somewhere on the button
+                        }
+                    }
+                }
+                this.events.push({
+                    clickX: clickEvent.clientX,
+                    clickY: clickEvent.clientY,
+                    mouseX: (_a = this.lastMousePosition) === null || _a === void 0 ? void 0 : _a.x,
+                    mouseY: (_b = this.lastMousePosition) === null || _b === void 0 ? void 0 : _b.y,
+                    rect,
+                    inViewport,
+                    position,
+                    timestamp: Date.now(),
+                });
+                // Notify detector - clicks are high-value events
+                this.notifyEvent(1.0);
+            };
+            element.addEventListener('click', listener);
+            this.clickListeners.set(element, listener);
+        });
+    }
+    stop() {
+        if (!this.isActive)
+            return;
+        this.isActive = false;
+        // Remove mouse listener
+        if (this.mouseListener) {
+            document.removeEventListener('mousemove', this.mouseListener);
+            this.mouseListener = null;
+        }
+        // Remove all click listeners
+        this.clickListeners.forEach((listener, element) => {
+            element.removeEventListener('click', listener);
+        });
+        this.clickListeners.clear();
+    }
+    reset() {
+        this.events = [];
+        this.lastMousePosition = null;
+    }
+    score() {
+        if (this.events.length === 0)
+            return undefined;
+        let totalScore = 0;
+        for (const click of this.events) {
+            switch (click.position) {
+                case 'no-mouse-data':
+                    totalScore += 0.0; // Bot - no mouse movement
+                    break;
+                case 'outside':
+                    totalScore += 0.0; // Bot - mouse not over target
+                    break;
+                case 'dead-center':
+                    totalScore += 0.5; // Suspicious - too perfect
+                    break;
+                case 'over-element':
+                    totalScore += 1.0; // Human - natural click
+                    break;
+            }
+        }
+        return totalScore / this.events.length;
+    }
+    getDebugInfo() {
+        return {
+            eventCount: this.events.length,
+            positions: {
+                noMouseData: this.events.filter(e => e.position === 'no-mouse-data').length,
+                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,
+            },
+            inViewport: this.events.filter(e => e.inViewport).length,
+            trackedElements: this.clickListeners.size,
+        };
+    }
+}
+exports.ClickStrategy = ClickStrategy;

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

@@ -0,0 +1,52 @@
+/**
+ * Environment Fingerprinting Strategy
+ * Captures browser environment on initialization and tick updates
+ */
+import { BaseStrategy } from '../strategy';
+interface EnvironmentData {
+    screenWidth: number;
+    screenHeight: number;
+    windowWidth: number;
+    windowHeight: number;
+    devicePixelRatio: number;
+    colorDepth: number;
+    userAgent: string;
+    platform: string;
+    language: string;
+    languages: string[];
+    hardwareConcurrency?: number;
+    maxTouchPoints: number;
+    vendor: string;
+    hasWebGL: boolean;
+    hasWebRTC: boolean;
+    hasLocalStorage: boolean;
+    hasSessionStorage: boolean;
+    hasIndexedDB: boolean;
+    plugins: number;
+    mimeTypes: number;
+    suspiciousRatio: boolean;
+    suspiciousDimensions: boolean;
+    featureInconsistency: boolean;
+    isMobile: boolean;
+    timestamp: number;
+}
+export declare class EnvironmentStrategy extends BaseStrategy {
+    readonly name = "environment";
+    readonly defaultWeight = 0.08;
+    private data;
+    start(): void;
+    stop(): void;
+    reset(): void;
+    onTick(_timestamp: number): void;
+    score(): number | undefined;
+    private isMobileDevice;
+    private captureEnvironment;
+    getDebugInfo(): EnvironmentData | null;
+    /**
+     * Check if current device is mobile
+     * Returns true if mobile, false otherwise
+     * Returns null if environment hasn't been captured yet
+     */
+    isMobile(): boolean | null;
+}
+export {};

package/dist/cjs/strategies/environment.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Environment Fingerprinting Strategy
+ * Captures browser environment on initialization and tick updates
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvironmentStrategy = void 0;
+const strategy_1 = require("../strategy");
+const math_utils_1 = require("../math-utils");
+class EnvironmentStrategy extends strategy_1.BaseStrategy {
+    constructor() {
+        super(...arguments);
+        this.name = 'environment';
+        this.defaultWeight = 0.08;
+        this.data = null;
+    }
+    start() {
+        this.captureEnvironment();
+    }
+    stop() {
+        // Environment data persists
+    }
+    reset() {
+        this.data = null;
+    }
+    onTick(_timestamp) {
+        // Re-capture environment periodically to detect changes
+        this.captureEnvironment();
+    }
+    score() {
+        if (!this.data)
+            return undefined;
+        const env = this.data;
+        let score = 0;
+        let factors = 0;
+        // Suspicious indicators
+        score += env.suspiciousDimensions ? 0.1 : 1.0;
+        score += env.suspiciousRatio ? 0.2 : 1.0;
+        score += env.featureInconsistency ? 0.3 : 1.0;
+        factors += 3;
+        // Browser features
+        const featureCount = [
+            env.hasWebGL,
+            env.hasLocalStorage,
+            env.hasSessionStorage,
+            env.hasIndexedDB,
+        ].filter(Boolean).length;
+        score += featureCount / 4;
+        factors++;
+        // Plugins
+        score += (0, math_utils_1.inverseSigmoid)(env.plugins, -2, -0.5);
+        score += (env.plugins > 0 ? 1.0 : 0.1);
+        factors += 2;
+        // Device
+        score += (0, math_utils_1.gaussian)(env.devicePixelRatio, 2, 1.5);
+        score += (env.colorDepth === 24 || env.colorDepth === 32) ? 1.0 : 0.4;
+        factors += 2;
+        return factors > 0 ? score / factors : undefined;
+    }
+    isMobileDevice() {
+        // Multiple checks for mobile detection
+        const hasTouchScreen = navigator.maxTouchPoints > 0 || 'ontouchstart' in window;
+        const mobileUA = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+        const smallScreen = window.innerWidth < 768 && window.innerHeight < 1024;
+        return (hasTouchScreen && smallScreen) || mobileUA;
+    }
+    captureEnvironment() {
+        try {
+            // WebGL detection
+            let hasWebGL = false;
+            try {
+                const canvas = document.createElement('canvas');
+                hasWebGL = !!(canvas.getContext('webgl') || canvas.getContext('experimental-webgl'));
+            }
+            catch (e) {
+                hasWebGL = false;
+            }
+            // WebRTC detection
+            const hasWebRTC = !!(window.RTCPeerConnection ||
+                window.mozRTCPeerConnection ||
+                window.webkitRTCPeerConnection);
+            // Mobile detection
+            const isMobile = this.isMobileDevice();
+            const windowWidth = window.innerWidth;
+            const windowHeight = window.innerHeight;
+            const screenWidth = window.screen.width;
+            const screenHeight = window.screen.height;
+            // Suspicious dimensions
+            const suspiciousDimensions = (windowWidth === 800 && windowHeight === 600) ||
+                (windowWidth === 1024 && windowHeight === 768) ||
+                (windowWidth === 1280 && windowHeight === 720) ||
+                (screenWidth === 800 && screenHeight === 600);
+            // Suspicious ratio
+            const windowScreenRatio = (windowWidth * windowHeight) / (screenWidth * screenHeight);
+            const suspiciousRatio = windowScreenRatio === 1.0 ||
+                windowScreenRatio < 0.1 ||
+                windowScreenRatio > 1.0;
+            // Feature inconsistency
+            const hasStorage = typeof localStorage !== 'undefined' && typeof sessionStorage !== 'undefined';
+            const featureInconsistency = (navigator.plugins.length === 0 && navigator.mimeTypes.length === 0) ||
+                !hasWebGL ||
+                !hasStorage;
+            this.data = {
+                screenWidth,
+                screenHeight,
+                windowWidth,
+                windowHeight,
+                devicePixelRatio: window.devicePixelRatio,
+                colorDepth: window.screen.colorDepth,
+                userAgent: navigator.userAgent,
+                platform: navigator.platform,
+                language: navigator.language,
+                languages: navigator.languages ? Array.from(navigator.languages) : [navigator.language],
+                hardwareConcurrency: navigator.hardwareConcurrency,
+                maxTouchPoints: navigator.maxTouchPoints || 0,
+                vendor: navigator.vendor,
+                hasWebGL,
+                hasWebRTC,
+                hasLocalStorage: typeof localStorage !== 'undefined',
+                hasSessionStorage: typeof sessionStorage !== 'undefined',
+                hasIndexedDB: 'indexedDB' in window,
+                plugins: navigator.plugins.length,
+                mimeTypes: navigator.mimeTypes.length,
+                suspiciousRatio,
+                suspiciousDimensions,
+                featureInconsistency,
+                isMobile,
+                timestamp: Date.now(),
+            };
+        }
+        catch (error) {
+            console.warn('Failed to capture environment:', error);
+        }
+    }
+    getDebugInfo() {
+        return this.data;
+    }
+    /**
+     * Check if current device is mobile
+     * Returns true if mobile, false otherwise
+     * Returns null if environment hasn't been captured yet
+     */
+    isMobile() {
+        var _a, _b;
+        return (_b = (_a = this.data) === null || _a === void 0 ? void 0 : _a.isMobile) !== null && _b !== void 0 ? _b : null;
+    }
+}
+exports.EnvironmentStrategy = EnvironmentStrategy;

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

@@ -0,0 +1,18 @@
+/**
+ * Detection Strategies - Modular behavior analysis
+ * Import only what you need for optimal bundle size
+ */
+export { MouseStrategy } from './mouse';
+export { ScrollStrategy } from './scroll';
+export { ClickStrategy } from './click';
+export { TapStrategy } from './tap';
+export { KeyboardStrategy } from './keyboard';
+export { EnvironmentStrategy } from './environment';
+export { ResizeStrategy } from './resize';
+export { MouseStrategy as Mouse } from './mouse';
+export { ScrollStrategy as Scroll } from './scroll';
+export { ClickStrategy as Click } from './click';
+export { TapStrategy as Tap } from './tap';
+export { KeyboardStrategy as Keyboard } from './keyboard';
+export { EnvironmentStrategy as Environment } from './environment';
+export { ResizeStrategy as Resize } from './resize';