@axeptio/behavior-detection 1.0.0

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

package/dist/strategies/keyboard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Keyboard Timing Detection Strategy
+ * Monitors typing in specific input fields
+ * Analyzes keydown/keyup timing and micro-variations
+ */
+import { BaseStrategy } from '../strategy';
+export declare class KeyboardStrategy extends BaseStrategy {
+    readonly name = "keyboard";
+    readonly defaultWeight = 0.1;
+    private events;
+    private targetSelectors;
+    private focusedElement;
+    private focusedElementSelector;
+    private lastEventTimestamp;
+    private sessionPauseThreshold;
+    private downListener;
+    private upListener;
+    private focusListeners;
+    private blurListeners;
+    private isActive;
+    constructor(options?: {
+        targetSelectors?: string[];
+    });
+    start(): void;
+    /**
+     * Add a new target selector at runtime
+     */
+    addTarget(selector: string): void;
+    private attachFocusListeners;
+    private attachFocusListenersForSelector;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    getDebugInfo(): {
+        eventCount: number;
+        downEvents: number;
+        upEvents: number;
+        backspaceCount: number;
+        pressDurations: number[];
+        focusedElement: string;
+        trackedElements: number;
+    };
+}

package/dist/strategies/mouse.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+import { BaseStrategy, type TimeSeriesPoint } from '../strategy';
+export declare class MouseStrategy extends BaseStrategy {
+    readonly name = "mouse";
+    readonly defaultWeight = 0.3;
+    private distanceSeries;
+    private angleSeries;
+    private lastPosition;
+    private lastAngle;
+    private cumulativeAngle;
+    private rollingWindowMs;
+    private listener;
+    private leaveListener;
+    private isActive;
+    private screenDiagonal;
+    constructor(options?: {
+        rollingWindow?: number;
+    });
+    start(): void;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    /**
+     * Mouse-specific pattern detection
+     * Detects bot-like patterns: constant velocity, linear paths
+     */
+    private detectMousePatterns;
+    getDebugInfo(): {
+        eventCount: number;
+        rollingWindow: number;
+        isActive: boolean;
+        distanceSeries: TimeSeriesPoint[];
+        angleSeries: TimeSeriesPoint[];
+    };
+}

package/dist/strategies/resize.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resize Behavior Detection Strategy
+ */
+import { BaseStrategy } from '../strategy';
+export declare class ResizeStrategy extends BaseStrategy {
+    readonly name = "resize";
+    readonly defaultWeight = 0.02;
+    private events;
+    private listener;
+    private isActive;
+    private lastMousePosition;
+    private mouseListener;
+    start(): void;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    getDebugInfo(): {
+        eventCount: number;
+        withMouseData: number;
+    };
+}

package/dist/strategies/scroll.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scroll Behavior Detection Strategy
+ * Autonomous module managing scroll event listeners
+ * Tracks normalized scroll distance and velocity patterns
+ */
+import { BaseStrategy, type TimeSeriesPoint } from '../strategy';
+export declare class ScrollStrategy extends BaseStrategy {
+    readonly name = "scroll";
+    readonly defaultWeight = 0.15;
+    private distanceSeries;
+    private velocitySeries;
+    private lastScrollY;
+    private lastTimestamp;
+    private rollingWindowMs;
+    private documentHeight;
+    private listener;
+    private isActive;
+    constructor(options?: {
+        rollingWindow?: number;
+    });
+    start(): void;
+    stop(): void;
+    reset(): void;
+    score(): number | undefined;
+    /**
+     * Scroll-specific pattern detection
+     * Detects bot-like patterns: constant deltas, instant jumps, too smooth
+     */
+    private detectScrollPatterns;
+    getDebugInfo(): {
+        eventCount: number;
+        rollingWindow: number;
+        isActive: boolean;
+        distanceSeries: TimeSeriesPoint[];
+        velocitySeries: TimeSeriesPoint[];
+    };
+}

package/dist/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/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/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/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@axeptio/behavior-detection",
+  "version": "1.0.0",
+  "description": "Lightweight behavior detection library to assess human likelihood of user sessions",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc --module commonjs --outDir dist/cjs",
+    "build:esm": "tsc --module es2015 --outDir dist/esm",
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist",
+    "build:bundle": "npm run build:esm && esbuild dist/esm/index.js --bundle --minify --sourcemap --target=es2020 --tree-shaking=true --outfile=dist/behavior-detection.esm.min.js",
+    "build:browser": "npm run build:esm && esbuild dist/esm/browser.js --bundle --minify --sourcemap --format=iife --target=es2017 --tree-shaking=true --drop:console --drop:debugger --outfile=dist/behavior-detection.min.js",
+    "build:browser:dev": "npm run build:esm && esbuild dist/esm/browser.js --bundle --minify --sourcemap --format=iife --global-name=BehaviorDetector --target=es2020 --tree-shaking=true --outfile=dist/behavior-detection.min.js",
+    "build:all": "npm run build && npm run build:bundle && npm run build:browser",
+    "clean": "rm -rf dist",
+    "deploy": "node scripts/deploy.js",
+    "release:patch": "npm version patch && git push && git push --tags",
+    "release:minor": "npm version minor && git push && git push --tags",
+    "release:major": "npm version major && git push && git push --tags",
+    "tryme": "npm run build && node scripts/serve.js",
+    "test": "npm run build && node tests/adversarial/run-tests.js",
+    "test:adversarial": "npm run build && node tests/adversarial/run-all.js",
+    "test:playwright": "npm run build && node tests/adversarial/playwright-test.js",
+    "test:selenium": "npm run build && node tests/adversarial/selenium-test.js",
+    "test:puppeteer": "npm run build && node tests/adversarial/puppeteer-test.js",
+    "test:stress": "npm run build && node tests/adversarial/detector-stress-test.js",
+    "test:stress:quick": "npm run build && node tests/adversarial/detector-stress-test.js --cycles=3 --duration=5000",
+    "test:stress:intense": "npm run build && node tests/adversarial/detector-stress-test.js --cycles=10 --duration=20000"
+  },
+  "keywords": [
+    "behavior-detection",
+    "bot-detection",
+    "user-tracking",
+    "analytics"
+  ],
+  "author": "Axeptio",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "latest",
+    "@playwright/test": "latest",
+    "puppeteer": "latest",
+    "selenium-webdriver": "latest",
+    "chromedriver": "latest",
+    "esbuild": "latest",
+    "@aws-sdk/client-s3": "^3.515.0",
+    "@aws-sdk/client-cloudfront": "^3.515.0"
+  }
+}