@axeptio/behavior-detection 1.0.0

package/dist/esm/strategies/tap.js

@@ -0,0 +1,210 @@
+/**
+ * Tap Behavior Detection Strategy (Mobile)
+ * Monitors touch interactions on specific elements
+ * Analyzes tap duration, precision, movement, and timing patterns
+ */
+import { BaseStrategy } from '../strategy';
+import { analyzeIntervals, scoreCoefficientOfVariation, gaussian } from '../math-utils';
+export class TapStrategy extends 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 = 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 += scoreCoefficientOfVariation(statistics.cv);
+                factors++;
+                // Ideal duration: 70-120ms
+                score += 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 += 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 = analyzeIntervals(intervals);
+            if (intervalAnalysis && !intervalAnalysis.allIdentical) {
+                score += 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,
+        };
+    }
+}

package/dist/esm/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/esm/strategy.js

@@ -0,0 +1,29 @@
+/**
+ * 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
+ */
+/**
+ * Base class for detection strategies
+ * Handles event callback pattern to avoid repetition
+ */
+export 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()
+            });
+        }
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,168 @@
+export type EventType = 'tab-visibility' | 'scroll' | 'resize' | 'mouse-move' | 'click' | 'keypress' | 'environment';
+export interface BaseEvent {
+    type: EventType;
+    timestamp: number;
+}
+export interface TabVisibilityEvent extends BaseEvent {
+    type: 'tab-visibility';
+    hidden: boolean;
+}
+export interface ScrollEvent extends BaseEvent {
+    type: 'scroll';
+    x: number;
+    y: number;
+    elementId?: string;
+    deltaY?: number;
+    deltaTime?: number;
+    velocity?: number;
+    isProgrammatic?: boolean;
+}
+export interface ResizeEvent extends BaseEvent {
+    type: 'resize';
+    width: number;
+    height: number;
+    mouseX?: number;
+    mouseY?: number;
+    mouseNearEdge?: boolean;
+    screenWidth: number;
+    screenHeight: number;
+    screenAvailWidth: number;
+    screenAvailHeight: number;
+    devicePixelRatio: number;
+    isFullscreen?: boolean;
+}
+export interface MouseMoveEvent extends BaseEvent {
+    type: 'mouse-move';
+    x: number;
+    y: number;
+    velocityX?: number;
+    velocityY?: number;
+    directionChange?: boolean;
+}
+export interface ClickEvent extends BaseEvent {
+    type: 'click';
+    x: number;
+    y: number;
+    targetX: number;
+    targetY: number;
+    targetWidth: number;
+    targetHeight: number;
+    distanceFromTarget: number;
+    mousePositionBeforeClick?: {
+        x: number;
+        y: number;
+        timestamp: number;
+    };
+    timeSinceLastMouseMove?: number;
+    targetInViewport: boolean;
+    targetVisibleArea: number;
+}
+export interface KeypressEvent extends BaseEvent {
+    type: 'keypress';
+    key: string;
+    timeSinceLastKey?: number;
+}
+export interface EnvironmentEvent extends BaseEvent {
+    type: 'environment';
+    screenWidth: number;
+    screenHeight: number;
+    screenAvailWidth: number;
+    screenAvailHeight: number;
+    windowWidth: number;
+    windowHeight: number;
+    devicePixelRatio: number;
+    colorDepth: number;
+    pixelDepth: number;
+    userAgent: string;
+    platform: string;
+    language: string;
+    languages: string[];
+    hardwareConcurrency?: number;
+    maxTouchPoints: number;
+    vendor: string;
+    hasWebGL: boolean;
+    hasWebRTC: boolean;
+    hasNotifications: boolean;
+    hasGeolocation: boolean;
+    hasIndexedDB: boolean;
+    hasLocalStorage: boolean;
+    hasSessionStorage: boolean;
+    plugins: number;
+    mimeTypes: number;
+    suspiciousRatio?: boolean;
+    suspiciousDimensions?: boolean;
+    featureInconsistency?: boolean;
+}
+export type TrackedEvent = TabVisibilityEvent | ScrollEvent | ResizeEvent | MouseMoveEvent | ClickEvent | KeypressEvent | EnvironmentEvent;
+export interface EventStorage {
+    'tab-visibility': TabVisibilityEvent[];
+    'scroll': ScrollEvent[];
+    'resize': ResizeEvent[];
+    'mouse-move': MouseMoveEvent[];
+    'click': ClickEvent[];
+    'keypress': KeypressEvent[];
+    'environment': EnvironmentEvent[];
+}
+export interface ScoreBreakdown {
+    overall: number;
+    factors: {
+        mouseMovement?: number;
+        clickAccuracy?: number;
+        scrollBehavior?: number;
+        keyboardTiming?: number;
+        tabActivity?: number;
+        resizeBehavior?: number;
+        environmentFingerprint?: number;
+    };
+    weights: {
+        mouseMovement: number;
+        clickAccuracy: number;
+        scrollBehavior: number;
+        keyboardTiming: number;
+        tabActivity: number;
+        resizeBehavior: number;
+        environmentFingerprint: number;
+    };
+}
+export interface ScoreOptions {
+    breakdown?: boolean;
+    auditTrail?: boolean;
+}
+export interface ScoreResult {
+    score: number;
+    breakdown?: ScoreBreakdown;
+    auditTrail?: TrackedEvent[];
+}
+export type ScoringFunction = (events: TrackedEvent[]) => number | undefined;
+export interface BehaviorSettings {
+    sampleRates?: {
+        mouseMove?: number;
+        scroll?: number;
+        keypress?: number;
+    };
+    rollingWindows?: {
+        mouseMove?: number;
+        scroll?: number;
+    };
+    weights?: {
+        mouseMovement?: number;
+        clickAccuracy?: number;
+        scrollBehavior?: number;
+        keyboardTiming?: number;
+        tabActivity?: number;
+        resizeBehavior?: number;
+        environmentFingerprint?: number;
+    };
+    customScorers?: {
+        mouseMovement?: ScoringFunction;
+        clickAccuracy?: ScoringFunction;
+        scrollBehavior?: ScoringFunction;
+        keyboardTiming?: ScoringFunction;
+        tabActivity?: ScoringFunction;
+        resizeBehavior?: ScoringFunction;
+        environmentFingerprint?: ScoringFunction;
+    };
+    clickMouseHistoryWindow?: number;
+    useWebWorker?: boolean;
+}
+export declare const DEFAULT_SETTINGS: Required<BehaviorSettings>;

package/dist/esm/types.js

@@ -0,0 +1,23 @@
+export const DEFAULT_SETTINGS = {
+    sampleRates: {
+        mouseMove: 0.1, // Track 10% of mouse moves
+        scroll: 1.0, // Track ALL scrolls - critical for detection
+        keypress: 1.0, // Track all keypresses
+    },
+    rollingWindows: {
+        mouseMove: 30000,
+        scroll: 30000,
+    },
+    weights: {
+        mouseMovement: 0.30, // Increased - continuous behavioral signal
+        clickAccuracy: 0.30, // Increased - critical behavioral signal
+        scrollBehavior: 0.15, // Unchanged
+        keyboardTiming: 0.10, // Slightly reduced
+        tabActivity: 0.05, // Unchanged
+        resizeBehavior: 0.02, // Reduced - less reliable
+        environmentFingerprint: 0.08, // Reduced - static signal, one-time check
+    },
+    customScorers: {},
+    clickMouseHistoryWindow: 1000,
+    useWebWorker: false, // Will implement Web Worker support in phase 2
+};

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @axeptio/behavior-detection
+ *
+ * Lightweight behavior detection library to assess human likelihood of user sessions
+ *
+ * @example Settings-based (all strategies included)
+ * ```ts
+ * import { BehaviorDetector } from '@axeptio/behavior-detection';
+ *
+ * const detector = new BehaviorDetector({
+ *   weights: {
+ *     mouseMovement: 0.3,
+ *     clickAccuracy: 0.3,
+ *   },
+ * });
+ *
+ * detector.start();
+ * const result = await detector.score({ breakdown: true });
+ * ```
+ *
+ * @example Strategy-based (tree-shakeable, import only what you need)
+ * ```ts
+ * import { BehaviorDetector, Mouse, Click, Keyboard } from '@axeptio/behavior-detection';
+ *
+ * const detector = new BehaviorDetector()
+ *   .addStrategy(new Mouse())
+ *   .addStrategy(new Click())
+ *   .addStrategy(new Keyboard());
+ *
+ * detector.start();
+ * const result = await detector.score();
+ * ```
+ */
+export { BehaviorDetector } from './behavior-detector';
+export type { DetectionStrategy, StrategyConfig } from './strategy';
+export { Mouse, Scroll, Click, Tap, Keyboard, Environment, Resize, MouseStrategy, ScrollStrategy, ClickStrategy, TapStrategy, KeyboardStrategy, EnvironmentStrategy, ResizeStrategy, } from './strategies/index.js';
+export type { BehaviorSettings, ScoreOptions, ScoreResult, ScoreBreakdown, TrackedEvent, EventType, ScoringFunction, } from './types';
+export { DEFAULT_SETTINGS } from './types';

package/dist/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/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;
+    };
+}