Lightweight behavior detection library to assess human likelihood of user sessions
npm install @axeptio/behavior-detection> Lightweight, privacy-first behavior detection library to distinguish human users from automated bots

![Tree-shakeable]()
A sophisticated JavaScript library that analyzes user behavior patterns to determine if interactions are human-like or bot-like. Unlike traditional CAPTCHA systems, this library works silently in the background, providing a seamless user experience while offering robust bot detection capabilities.
- ๐ฏ High Accuracy: Multi-strategy detection approach with configurable weights
- ๐ค Automation Detection: Immediate detection of navigator.webdriver, headless browsers, and automation frameworks
- ๐ฒ Tree-shakeable: Import only the strategies you need
- ๐ Zero Dependencies: Lightweight and fast (< 15KB minified)
- ๐ฑ Cross-platform: Works on desktop and mobile browsers
- ๐ Privacy-first: All processing happens client-side, no data sent to servers
- โก Real-time: Continuously monitors and scores user behavior
- ๐จ Framework Agnostic: Works with vanilla JS, React, Vue, Angular, etc.
- ๐ฆ Multiple Build Formats: ESM, CommonJS, and IIFE (browser CDN)
- ๐งช Battle-tested: Comprehensive adversarial testing against Playwright, Puppeteer, and Selenium
Try the interactive test harness locally:
``bash`
npm run tryme
This will build the library and open the comprehensive test harness in your browser, showing real-time detection scores and visualizations as you interact with the page.
Demo Files:
- demos/test-harness.html - Full-featured interactive test harness with real-time graphsdemos/browser-demo.html
- - Simple CDN usage example with auto-initializationdemos/example.html
- - Strategy-based usage example with detailed visualizations
`bash`
npm install @axeptio/behavior-detectionor
yarn add @axeptio/behavior-detection
`html`
Import only the strategies you need for optimal bundle size:
`typescript
import {
BehaviorDetector,
Mouse,
Click,
Keyboard,
Environment,
Timing,
Visibility
} from '@axeptio/behavior-detection';
const detector = new BehaviorDetector()
.addStrategy(new Mouse())
.addStrategy(new Click())
.addStrategy(new Keyboard())
.addStrategy(new Environment()) // Detects automation frameworks
.addStrategy(new Timing()) // Detects machine-like timing
.addStrategy(new Visibility()); // Detects hidden tab actions
// Start tracking
detector.start();
// Get score (0 = bot-like, 1 = human-like)
const result = await detector.score({ breakdown: true });
console.log('Human likelihood:', result.score);
console.log('Breakdown:', result.breakdown);
// Stop tracking when done
detector.stop();
`
`html
Interact with this page
`
#### React
`tsx
import { useEffect, useRef } from 'react';
import { BehaviorDetector, Mouse, Click, Scroll } from '@axeptio/behavior-detection';
function App() {
const detectorRef = useRef
useEffect(() => {
const detector = new BehaviorDetector()
.addStrategy(new Mouse())
.addStrategy(new Click())
.addStrategy(new Scroll());
detector.start();
detectorRef.current = detector;
// Check score periodically
const interval = setInterval(async () => {
const result = await detector.score();
if (result.score < 0.3) {
console.warn('Bot detected!');
// Show CAPTCHA or take other action
}
}, 3000);
return () => {
clearInterval(interval);
detector.stop();
};
}, []);
return
#### Vue
`vue
Your app content
`๐ฏ Detection Strategies
The library uses multiple autonomous detection strategies, each analyzing different aspects of user behavior:
$3
Weight: 0.30 (default)
Analyzes mouse movement patterns for human-like characteristics:
- Velocity Variation: Humans have natural acceleration/deceleration (CV ~0.8-1.2)
- Direction Changes: Organic curves vs. linear interpolation
- Movement Smoothness: Natural micro-corrections vs. perfect paths
- Entry Point Analysis: Where mouse enters the viewport
- Micro-movement Detection: Natural hand tremor (1-5px jitter)
`typescript
import { MouseStrategy } from '@axeptio/behavior-detection';const mouse = new MouseStrategy({
rollingWindow: 5000 // Keep last 5 seconds of data
});
detector.addStrategy(mouse, 0.30); // Custom weight
`Bot Indicators:
- Constant velocity movements
- Perfect straight lines or curves
- Instant position jumps
- No micro-corrections or hand tremor
- Entry at (0,0) or exact viewport center
- No micro-movements (1-5px) before actions
$3
Weight: 0.30 (default)
Monitors click positioning accuracy and timing on interactive elements:
`typescript
import { ClickStrategy } from '@axeptio/behavior-detection';const click = new ClickStrategy({
targetSelectors: ['button', 'a', '[role="button"]']
});
detector.addStrategy(click);
// Add custom targets dynamically
click.addTarget('.custom-clickable');
`Detection Patterns:
- โ
Human: Mouse positioned over element before click
- โ ๏ธ Suspicious: Click at exact center (pixel-perfect)
- โ Bot: Click without mouse movement or mouse outside element
Enhanced Detection (v1.1+):
| Signal | Human | Bot |
|--------|-------|-----|
| Mouse-click position delta | 0px (exact match) | > 5px (mismatched) |
| Time since last mousemove | 50-300ms | < 10ms or > 2000ms |
|
isTrusted event property | true | false (programmatic) |Bots using
element.click() often have click event coordinates that don't match the last mouse position, which is a strong indicator of programmatic clicks.$3
Weight: 0.15 (default)
Analyzes scrolling behavior patterns:
`typescript
import { ScrollStrategy } from '@axeptio/behavior-detection';const scroll = new ScrollStrategy({
rollingWindow: 5000
});
`Bot Indicators:
- Identical scroll distances (smoking gun)
- Instant jumps (programmatic scrollTo)
- Too consistent velocity
- No natural acceleration/deceleration
$3
Weight: 0.10 (default)
Examines typing patterns and timing:
`typescript
import { KeyboardStrategy } from '@axeptio/behavior-detection';const keyboard = new KeyboardStrategy({
targetSelectors: ['input[type="text"]', 'textarea']
});
// Add custom input targets
keyboard.addTarget('#custom-input');
`Detection Factors:
- Keystroke interval variation (natural human timing has CV ~0.4-0.6)
- Key press duration variance
- Backspace usage (error correction = human)
- Too fast/instant key releases (<5ms = bot)
$3
Weight: 0.35 (mobile default)
Mobile-specific touch interaction detection:
`typescript
import { TapStrategy } from '@axeptio/behavior-detection';const tap = new TapStrategy({
targetSelectors: ['button', 'a']
});
`Analyzes:
- Touch pressure patterns
- Tap duration and timing
- Multi-touch gestures
$3
Weight: 0.08 (default)
Fingerprints browser environment for automation indicators. This strategy provides immediate bot detection for the most reliable automation signals.
`typescript
import { EnvironmentStrategy } from '@axeptio/behavior-detection';const env = new EnvironmentStrategy();
// Check if automation is detected
if (env.isLikelyBot()) {
console.warn('Automation detected!');
}
// Get detailed automation indicators
const indicators = env.getAutomationIndicators();
console.log(indicators);
// {
// isWebdriver: true, // navigator.webdriver === true
// hasHeadlessUA: false, // HeadlessChrome in user agent
// hasChromelessRuntime: true, // Chrome without chrome.runtime
// hasSoftwareRenderer: false, // SwiftShader WebGL renderer
// hasAutomationGlobals: false, // Selenium, Phantom, etc. globals
// hasCDPInjection: false, // Chrome DevTools Protocol injection
// ...
// }
`Immediate Disqualification Signals (returns very low scores):
| Signal | Score | Description |
|--------|-------|-------------|
|
navigator.webdriver === true | 0.05 | Most reliable automation indicator |
| Automation globals detected | 0.10 | Selenium, Phantom, Nightmare, etc. |
| CDP injection (cdc_* properties) | 0.10 | Chrome DevTools Protocol |
| Multiple headless indicators | 0.15 | Combined headless signals |
| HeadlessChrome in user agent | 0.20 | Explicit headless mode |Automation Globals Detected:
-
__selenium_evaluate, __webdriver_evaluate, __driver_evaluate
- _phantom, callPhantom, __nightmare
- _Selenium_IDE_Recorder, domAutomation, domAutomationController
- And more...Additional Checks:
- Suspicious dimensions (800x600, 1024x768)
- Missing browser features (WebGL, localStorage)
- Plugin/MIME type inconsistencies
- Software WebGL renderer (SwiftShader)
- Chrome without
chrome.runtime (headless indicator)$3
Weight: 0.02 (default)
Monitors window resize behavior:
`typescript
import { ResizeStrategy } from '@axeptio/behavior-detection';const resize = new ResizeStrategy();
`Detects:
- Programmatic resizing patterns
- Suspicious resize timing
- Mouse position during resize
$3
Weight: 0.15 (default)
Analyzes timing patterns in user interactions to detect bot-like precision:
`typescript
import { TimingStrategy } from '@axeptio/behavior-detection';const timing = new TimingStrategy();
`Detection Signals:
| Signal | Human Behavior | Bot Behavior |
|--------|---------------|--------------|
| Pre-action stillness | Micro-movements (1-5px tremor) | Perfect stillness |
| Mouse-to-click delay | 50-300ms with variation | 0-10ms (instant) |
| Action intervals | Variable timing | Machine-precise (100ms, 500ms, 1000ms) |
| Hidden tab actions | None (can't interact) | Continues while hidden |
Bot Indicators:
- Zero mouse movement before clicks (perfect stillness)
- Suspiciously consistent action intervals (CV < 0.15)
- Actions at machine-precise intervals (multiples of 100ms, 500ms)
- Any actions while
document.hidden === true$3
Weight: 0.10 (default)
Monitors tab visibility and focus patterns:
`typescript
import { VisibilityStrategy } from '@axeptio/behavior-detection';const visibility = new VisibilityStrategy();
`Detection Signals:
| Signal | Human Behavior | Bot Behavior |
|--------|---------------|--------------|
| Actions while hidden | Impossible | Continues normally |
| Resume delay | 100-500ms to refocus | Instant (< 50ms) |
| Focus-to-type delay | 100-500ms natural delay | Instant (< 20ms) |
Bot Indicators:
- Actions occurring while
document.hidden === true
- Instant activity resume when tab becomes visible
- Typing immediately after focus without human reaction time๐ API Reference
$3
Main class for managing detection strategies.
#### Constructor
`typescript
constructor(options?: TickOptions)
`Options:
-
interval?: number - Tick interval in milliseconds (default: 1000)
- pauseOnHidden?: boolean - Automatically pause detection when tab is hidden (default: true)#### Methods
#####
addStrategy(strategy: DetectionStrategy, weight?: number): thisAdd a detection strategy with optional custom weight.
`typescript
detector.addStrategy(new Mouse(), 0.35);
`#####
removeStrategy(name: string): thisRemove a strategy by name.
`typescript
detector.removeStrategy('mouse');
`#####
setStrategyEnabled(name: string, enabled: boolean): thisEnable or disable a strategy without removing it.
`typescript
detector.setStrategyEnabled('mouse', false);
`#####
start(): voidStart all enabled strategies.
`typescript
detector.start();
`#####
stop(): voidStop all strategies and cleanup listeners.
`typescript
detector.stop();
`#####
reset(): voidClear all collected data without stopping.
`typescript
detector.reset();
`#####
score(options?: ScoreOptions): PromiseCalculate the human likelihood score.
`typescript
const result = await detector.score({
breakdown: true, // Include per-strategy scores
});
`ScoreOptions:
-
breakdown?: boolean - Include detailed breakdown of each strategyScoreResult:
`typescript
{
score: number; // 0-1 (0=bot, 1=human)
breakdown?: {
overall: number;
factors: {
mouse?: number;
click?: number;
scroll?: number;
keyboard?: number;
environment?: number;
// ...
};
weights: {
mouse: number;
click: number;
// ...
};
};
}
`#####
isActive(): booleanCheck if detector is currently tracking.
`typescript
if (detector.isActive()) {
console.log('Detector is running');
}
`#####
isPaused(): booleanCheck if detector is currently paused due to tab visibility.
`typescript
if (detector.isPaused()) {
console.log('Detector is paused (tab hidden)');
}
`Note: A detector can be both active and paused. When the tab is hidden with
pauseOnHidden: true, the detector remains active but is temporarily paused.#####
getEventCount(): RecordGet event counts from all strategies.
#####
getStrategyDebugInfo(): RecordGet debug information from all strategies.
#####
destroy(): voidComplete cleanup and remove all strategies.
`typescript
detector.destroy();
`โ๏ธ Configuration
$3
Customize how much each strategy contributes to the final score:
`typescript
const detector = new BehaviorDetector()
.addStrategy(new Mouse(), 0.40) // 40% weight
.addStrategy(new Click(), 0.35) // 35% weight
.addStrategy(new Scroll(), 0.15) // 15% weight
.addStrategy(new Keyboard(), 0.10); // 10% weight
`$3
The library automatically adjusts strategies based on device type:
Desktop (default):
- Mouse: 0.30
- Click: 0.30
- Scroll: 0.15
- Keyboard: 0.10
- Environment: 0.08
- Resize: 0.02
Mobile (automatic):
- Tap: 0.35 (replaces click)
- Scroll: 0.35 (increased)
- Keyboard: 0.15
- Environment: 0.10
- Resize: 0.05
$3
Control how often strategies receive tick updates:
`typescript
const detector = new BehaviorDetector({
interval: 500 // Check every 500ms
});
`$3
By default, the detector automatically pauses when the browser tab becomes hidden (using the Page Visibility API) and resumes when the tab becomes visible again. This provides several benefits:
- Better Performance: Saves CPU cycles when the tab isn't visible
- Battery Life: Reduces power consumption on mobile devices
- Accuracy: Avoids collecting misleading data from background tabs
`typescript
// Default: pause on hidden (recommended)
const detector = new BehaviorDetector({
pauseOnHidden: true // Default
});// Disable if you need to track background behavior
const detector = new BehaviorDetector({
pauseOnHidden: false
});
// Check if currently paused
if (detector.isPaused()) {
console.log('Detection is paused (tab hidden)');
}
`Browser CDN Usage:
`javascript
window.bdSettings = {
autoStart: true,
pauseOnHidden: true, // Default: true
// ... other settings
};
`The detector remains "active" (via
isActive()) while paused, but strategies and tick updates are temporarily stopped until the tab becomes visible again. All collected data is preserved during the pause.๐จ Browser Support
- โ
Chrome/Edge 90+
- โ
Firefox 88+
- โ
Safari 14+
- โ
Mobile Safari (iOS 14+)
- โ
Chrome Mobile (Android 90+)
๐งช Testing & Validation
The library includes comprehensive adversarial testing against popular automation frameworks:
$3
`bash
npm run test:adversarial
`$3
`bash
Test against Playwright
npm run test:playwrightTest against Puppeteer
npm run test:puppeteerTest against Selenium
npm run test:seleniumStress test (extensive scenarios)
npm run test:stress
`$3
Each framework is tested with:
1. Bot-like behavior - Rapid actions, no delays (expected: score < 0.4)
2. Human-like behavior - Natural delays and movements (expected: score > 0.6)
3. Stealth mode - Automation with evasion techniques
4. Headless vs Headed - Different browser modes
See tests/adversarial/README.md for detailed testing documentation.
๐๏ธ Architecture
$3
Each detection strategy is a fully autonomous module:
`typescript
interface DetectionStrategy {
readonly name: string;
readonly defaultWeight: number;
start(): void; // Register listeners
stop(): void; // Cleanup
reset(): void; // Clear data
score(): number | undefined; // Calculate score
onTick?(timestamp: number): void; // Optional polling
getDebugInfo?(): any; // Optional debug data
}
`Benefits:
- ๐ฒ Tree-shakeable (import only what you need)
- ๐ Fully autonomous (manages own listeners and state)
- ๐ฏ Single responsibility
- ๐งฉ Easy to extend with custom strategies
$3
Uses smooth mathematical functions instead of magic numbers:
`typescript
import { gaussian, sigmoid, inverseSigmoid } from './math-utils';// Gaussian: ideal value with symmetric falloff
score = gaussian(actualCV, idealCV, width);
// Sigmoid: smooth 0-1 mapping
score = sigmoid(value, midpoint, steepness);
// Inverse sigmoid: penalize high values
score = inverseSigmoid(value, midpoint, steepness);
`๐ Performance
- Minimal CPU Impact: Sampling and rolling windows prevent data buildup
- Memory Efficient: ~1-2MB typical memory usage
- No Network Calls: Everything runs client-side
- Async Scoring: Non-blocking score calculations
๐ Privacy & Security
- โ
Client-side only: No data transmitted to servers
- โ
No PII collected: Only behavioral patterns (no keystrokes content)
- โ
GDPR friendly: No cookies, no tracking, no storage
- โ
Transparent: Open source and auditable
๐ ๏ธ Development
$3
`bash
Build all formats (ESM, CJS, IIFE)
npm run build:allBuild only ESM/CJS
npm run buildBuild browser bundle
npm run build:browser
`$3
`
behavior-detection/
โโโ src/
โ โโโ behavior-detector.ts # Main detector class
โ โโโ strategy.ts # Strategy interface
โ โโโ types.ts # TypeScript types
โ โโโ math-utils.ts # Mathematical functions
โ โโโ browser.ts # Browser CDN wrapper
โ โโโ strategies/
โ โโโ mouse.ts # Mouse movement + entry point detection
โ โโโ click.ts # Click accuracy + position delta
โ โโโ scroll.ts # Scroll behavior detection
โ โโโ keyboard.ts # Keyboard timing detection
โ โโโ tap.ts # Mobile tap detection
โ โโโ environment.ts # Automation + headless detection
โ โโโ timing.ts # Action timing patterns
โ โโโ visibility.ts # Tab visibility behavior
โ โโโ resize.ts # Window resize detection
โโโ dist/ # Build output
โโโ demos/
โ โโโ test-harness.html # Interactive testing UI with graphs
โ โโโ browser-demo.html # CDN usage example
โ โโโ example.html # Strategy-based usage example
โโโ tests/
โ โโโ adversarial/ # Automation framework tests
โโโ docs/ # Documentation assets
`$3
`bash
npm run build # Build library (ESM + CJS)
npm run build:all # Build all formats
npm run build:browser # Build browser IIFE bundle
npm run clean # Clean dist directory
npm run tryme # Build and start demo server
npm run deploy # Deploy to CDN (AWS S3/CloudFront)
npm run test # Run basic tests
npm run test:adversarial # Run all adversarial tests
npm run test:stress # Stress test with extensive scenarios
`๐ค Contributing
Contributions are welcome! This library can be extended with:
- New strategies: Add detection for new behavioral patterns
- Improved algorithms: Enhance existing detection logic
- Mobile optimizations: Better touch/gesture detection
- Performance improvements: Reduce overhead
- Test coverage: Add more adversarial test scenarios
$3
`typescript
import { DetectionStrategy } from '@axeptio/behavior-detection';export class CustomStrategy implements DetectionStrategy {
readonly name = 'custom';
readonly defaultWeight = 0.10;
private data: any[] = [];
private listener: any;
start(): void {
this.listener = (e: Event) => {
// Collect data
this.data.push(/ ... /);
};
document.addEventListener('someevent', this.listener);
}
stop(): void {
if (this.listener) {
document.removeEventListener('someevent', this.listener);
}
}
reset(): void {
this.data = [];
}
score(): number | undefined {
if (this.data.length < 5) return undefined;
// Calculate and return score (0-1)
return 0.85;
}
getDebugInfo() {
return {
eventCount: this.data.length,
data: this.data
};
}
}
``- Form Protection: Detect automated form submissions
- Account Security: Identify credential stuffing attacks
- E-commerce: Prevent inventory hoarding bots
- Analytics: Filter bot traffic from user metrics
- Rate Limiting: Adaptive limits based on behavior
- A/B Testing: Exclude bots from experiments
- Progressive CAPTCHAs: Only show CAPTCHA to suspicious users
Recommended score interpretation:
| Score Range | Interpretation | Action |
|-------------|---------------|--------|
| 0.8 - 1.0 | Very likely human | Full access |
| 0.6 - 0.8 | Probably human | Monitor |
| 0.3 - 0.6 | Suspicious | Add friction (CAPTCHA) |
| 0.0 - 0.3 | Very likely bot | Block or severely limit |
Note: Thresholds should be tuned based on your specific use case and acceptable false positive rate.
- Not foolproof: Sophisticated bots with human-like behavior can evade detection
- Initial period: Requires user interaction to build confidence
- False positives: Accessibility tools, keyboard-only navigation may score lower
- Context matters: Some legitimate use cases (automation testing, scripts) will be flagged
Best Practice: Use as one layer in a defense-in-depth strategy, not as the sole security measure.
Proprietary ยฉ Axeptio
- Inspired by research in behavioral biometrics and bot detection
- Built with TypeScript for type safety
- Tested against real-world automation frameworks
- Mathematical approach based on statistical pattern recognition
---
Made with โค๏ธ by Axeptio