@axeptio/behavior-detection 1.0.0

package/dist/cjs/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/cjs/types.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SETTINGS = void 0;
+exports.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/esm/behavior-detector.d.ts

@@ -0,0 +1,102 @@
+import type { ScoreOptions, ScoreResult } from './types';
+import type { DetectionStrategy, StrategyConfig, TickOptions } from './strategy';
+/**
+ * Main class for behavior detection
+ * Uses modular strategy pattern for tree-shakeable, autonomous detection modules
+ */
+export declare class BehaviorDetector {
+    private strategies;
+    private isTracking;
+    private isPausedByVisibility;
+    private tickInterval;
+    private tickIntervalMs;
+    private pauseOnHidden;
+    private visibilityChangeHandler;
+    private confidenceScore;
+    private readonly CONFIDENCE_TARGET;
+    private readonly CONFIDENCE_DECAY;
+    constructor(tickOptions?: TickOptions);
+    /**
+     * Add a detection strategy
+     */
+    addStrategy(strategy: DetectionStrategy, weight?: number): this;
+    /**
+     * Handle event from strategy - update confidence
+     */
+    private onStrategyEvent;
+    /**
+     * Remove a detection strategy
+     */
+    removeStrategy(name: string): this;
+    /**
+     * Enable/disable a strategy
+     */
+    setStrategyEnabled(name: string, enabled: boolean): this;
+    /**
+     * Get all registered strategies
+     */
+    getStrategies(): ReadonlyMap<string, StrategyConfig>;
+    /**
+     * Start tracking
+     */
+    start(): void;
+    /**
+     * Stop tracking
+     */
+    stop(): void;
+    /**
+     * Reset all data
+     */
+    reset(): void;
+    /**
+     * Calculate human likelihood score
+     */
+    score(options?: ScoreOptions): Promise<ScoreResult>;
+    /**
+     * Check if currently tracking
+     */
+    isActive(): boolean;
+    /**
+     * Check if currently paused due to tab visibility
+     */
+    isPaused(): boolean;
+    /**
+     * Get event count from all strategies
+     */
+    getEventCount(): Record<string, number>;
+    /**
+     * Get debug info from all strategies
+     */
+    getStrategyDebugInfo(): Record<string, any>;
+    /**
+     * Get current confidence score (0-1)
+     * Represents how much interaction data we've collected
+     * Higher confidence = more reliable classification
+     */
+    getConfidence(): number;
+    /**
+     * Check if confidence is above threshold for reliable classification
+     * @param threshold - Minimum confidence (0-1), default 0.3
+     */
+    hasConfidentData(threshold?: number): boolean;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+    /**
+     * Handle visibility change events
+     */
+    private handleVisibilityChange;
+    /**
+     * Start tick mechanism for strategies
+     */
+    private startTick;
+    /**
+     * Stop tick mechanism
+     */
+    private stopTick;
+    /**
+     * Calculate score using strategies
+     */
+    private calculateStrategyScore;
+}

package/dist/esm/behavior-detector.js

@@ -0,0 +1,311 @@
+/**
+ * Main class for behavior detection
+ * Uses modular strategy pattern for tree-shakeable, autonomous detection modules
+ */
+export class BehaviorDetector {
+    constructor(tickOptions) {
+        // Strategy mode
+        this.strategies = new Map();
+        this.isTracking = false;
+        this.isPausedByVisibility = false;
+        this.tickInterval = null;
+        this.tickIntervalMs = 1000; // Default: 1 second
+        this.pauseOnHidden = true;
+        this.visibilityChangeHandler = null;
+        // Confidence tracking
+        this.confidenceScore = 0;
+        this.CONFIDENCE_TARGET = 1.0; // Target confidence for reliable classification
+        this.CONFIDENCE_DECAY = 0.95; // Per event decay to prevent infinite growth
+        if (tickOptions === null || tickOptions === void 0 ? void 0 : tickOptions.interval) {
+            this.tickIntervalMs = tickOptions.interval;
+        }
+        if ((tickOptions === null || tickOptions === void 0 ? void 0 : tickOptions.pauseOnHidden) !== undefined) {
+            this.pauseOnHidden = tickOptions.pauseOnHidden;
+        }
+    }
+    /**
+     * Add a detection strategy
+     */
+    addStrategy(strategy, weight) {
+        const config = {
+            strategy,
+            weight: weight !== null && weight !== void 0 ? weight : strategy.defaultWeight,
+            enabled: true,
+        };
+        this.strategies.set(strategy.name, config);
+        // Set up event callback for confidence tracking
+        if (strategy.setEventCallback) {
+            strategy.setEventCallback((event) => {
+                this.onStrategyEvent(event, config.weight);
+            });
+        }
+        // If already tracking, start this strategy immediately
+        if (this.isTracking) {
+            strategy.start();
+        }
+        return this;
+    }
+    /**
+     * Handle event from strategy - update confidence
+     */
+    onStrategyEvent(event, strategyWeight) {
+        // Apply decay to existing confidence to prevent infinite growth
+        this.confidenceScore *= this.CONFIDENCE_DECAY;
+        // Add weighted contribution from this event
+        // eventWeight (0-1) * strategyWeight (e.g. 0.3 for mouse) = contribution
+        const contribution = event.weight * strategyWeight;
+        this.confidenceScore = Math.min(this.CONFIDENCE_TARGET, this.confidenceScore + contribution);
+    }
+    /**
+     * Remove a detection strategy
+     */
+    removeStrategy(name) {
+        const config = this.strategies.get(name);
+        if (config) {
+            if (this.isTracking) {
+                config.strategy.stop();
+            }
+            this.strategies.delete(name);
+        }
+        return this;
+    }
+    /**
+     * Enable/disable a strategy
+     */
+    setStrategyEnabled(name, enabled) {
+        const config = this.strategies.get(name);
+        if (config) {
+            config.enabled = enabled;
+            // If tracking and being disabled, stop it
+            if (!enabled && this.isTracking) {
+                config.strategy.stop();
+            }
+            // If tracking and being enabled, start it
+            if (enabled && this.isTracking) {
+                config.strategy.start();
+            }
+        }
+        return this;
+    }
+    /**
+     * Get all registered strategies
+     */
+    getStrategies() {
+        return this.strategies;
+    }
+    /**
+     * Start tracking
+     */
+    start() {
+        if (this.isTracking)
+            return;
+        this.isTracking = true;
+        // Set up visibility change listener
+        if (this.pauseOnHidden && typeof document !== 'undefined') {
+            this.visibilityChangeHandler = this.handleVisibilityChange.bind(this);
+            document.addEventListener('visibilitychange', this.visibilityChangeHandler);
+            // Check initial visibility state
+            if (document.hidden) {
+                this.isPausedByVisibility = true;
+                return; // Don't start strategies if already hidden
+            }
+        }
+        // Start all enabled strategies
+        for (const [_, config] of this.strategies) {
+            if (config.enabled) {
+                config.strategy.start();
+            }
+        }
+        // Start tick mechanism
+        this.startTick();
+    }
+    /**
+     * Stop tracking
+     */
+    stop() {
+        if (!this.isTracking)
+            return;
+        this.isTracking = false;
+        this.isPausedByVisibility = false;
+        // Remove visibility change listener
+        if (this.visibilityChangeHandler && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.visibilityChangeHandler);
+            this.visibilityChangeHandler = null;
+        }
+        // Stop all strategies
+        for (const [_, config] of this.strategies) {
+            config.strategy.stop();
+        }
+        // Stop tick
+        this.stopTick();
+    }
+    /**
+     * Reset all data
+     */
+    reset() {
+        this.confidenceScore = 0;
+        for (const [_, config] of this.strategies) {
+            config.strategy.reset();
+        }
+    }
+    /**
+     * Calculate human likelihood score
+     */
+    async score(options = {}) {
+        const breakdown = this.calculateStrategyScore();
+        const result = {
+            score: breakdown.overall,
+        };
+        if (options.breakdown) {
+            result.breakdown = breakdown;
+        }
+        // Note: auditTrail not available in strategy mode
+        // Each strategy manages its own data independently
+        return result;
+    }
+    /**
+     * Check if currently tracking
+     */
+    isActive() {
+        return this.isTracking;
+    }
+    /**
+     * Check if currently paused due to tab visibility
+     */
+    isPaused() {
+        return this.isPausedByVisibility;
+    }
+    /**
+     * Get event count from all strategies
+     */
+    getEventCount() {
+        var _a, _b;
+        const counts = {};
+        for (const [name, config] of this.strategies) {
+            const debug = (_b = (_a = config.strategy).getDebugInfo) === null || _b === void 0 ? void 0 : _b.call(_a);
+            if ((debug === null || debug === void 0 ? void 0 : debug.eventCount) !== undefined) {
+                counts[name] = debug.eventCount;
+            }
+        }
+        return counts;
+    }
+    /**
+     * Get debug info from all strategies
+     */
+    getStrategyDebugInfo() {
+        const debug = {};
+        for (const [name, config] of this.strategies) {
+            if (config.strategy.getDebugInfo) {
+                debug[name] = config.strategy.getDebugInfo();
+            }
+        }
+        return debug;
+    }
+    /**
+     * Get current confidence score (0-1)
+     * Represents how much interaction data we've collected
+     * Higher confidence = more reliable classification
+     */
+    getConfidence() {
+        return Math.min(1, this.confidenceScore);
+    }
+    /**
+     * Check if confidence is above threshold for reliable classification
+     * @param threshold - Minimum confidence (0-1), default 0.3
+     */
+    hasConfidentData(threshold = 0.3) {
+        return this.getConfidence() >= threshold;
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        this.stop();
+        this.strategies.clear();
+    }
+    /**
+     * Handle visibility change events
+     */
+    handleVisibilityChange() {
+        if (!this.isTracking)
+            return;
+        if (document.hidden) {
+            // Tab became hidden - pause detection
+            if (!this.isPausedByVisibility) {
+                this.isPausedByVisibility = true;
+                // Stop all strategies
+                for (const [_, config] of this.strategies) {
+                    if (config.enabled) {
+                        config.strategy.stop();
+                    }
+                }
+                // Stop tick
+                this.stopTick();
+            }
+        }
+        else {
+            // Tab became visible - resume detection
+            if (this.isPausedByVisibility) {
+                this.isPausedByVisibility = false;
+                // Restart all enabled strategies
+                for (const [_, config] of this.strategies) {
+                    if (config.enabled) {
+                        config.strategy.start();
+                    }
+                }
+                // Restart tick
+                this.startTick();
+            }
+        }
+    }
+    /**
+     * Start tick mechanism for strategies
+     */
+    startTick() {
+        if (this.tickInterval !== null)
+            return;
+        this.tickInterval = window.setInterval(() => {
+            const now = Date.now();
+            for (const [_, config] of this.strategies) {
+                if (config.enabled && config.strategy.onTick) {
+                    config.strategy.onTick(now);
+                }
+            }
+        }, this.tickIntervalMs);
+    }
+    /**
+     * Stop tick mechanism
+     */
+    stopTick() {
+        if (this.tickInterval !== null) {
+            clearInterval(this.tickInterval);
+            this.tickInterval = null;
+        }
+    }
+    /**
+     * Calculate score using strategies
+     */
+    calculateStrategyScore() {
+        const factors = {};
+        const weights = {};
+        let totalWeight = 0;
+        let weightedSum = 0;
+        for (const [name, config] of this.strategies) {
+            if (!config.enabled)
+                continue;
+            const score = config.strategy.score();
+            factors[name] = score;
+            weights[name] = config.weight;
+            if (score !== undefined && score !== null) {
+                totalWeight += config.weight;
+                weightedSum += score * config.weight;
+            }
+        }
+        const overall = totalWeight > 0 ? weightedSum / totalWeight : 0.5;
+        return {
+            overall: Math.max(0, Math.min(1, overall)),
+            factors,
+            weights,
+        };
+    }
+}

package/dist/esm/browser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser Build - Auto-initializing standalone bundle for CDN usage
+ *
+ * Usage:
+ * <script src="https://cdn.../behavior-detector.js"></script>
+ * <script>
+ * window.bdSettings = {
+ *   strategies: {
+ *     mouse: { weight: 0.3 },
+ *     scroll: { weight: 0.15 },
+ *     click: { weight: 0.3 },
+ *     keyboard: { weight: 0.1 },
+ *     environment: { weight: 0.08 },
+ *     resize: { weight: 0.02 }
+ *   },
+ *   autoStart: true,
+ *   checkMs: 2000,
+ *   pauseOnHidden: true,  // Auto-pause when tab hidden (default: true)
+ *   onScore: (result) => {
+ *     console.log('Human likelihood:', result.score);
+ *     if (result.score < 0.3) {
+ *       // Likely bot
+ *     }
+ *   },
+ *   ifBot: (result) => {
+ *     // Called when score < threshold
+ *     console.warn('Bot detected:', result);
+ *   },
+ *   botThreshold: 0.3
+ * }
+ * </script>
+ */
+export {};