@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.

✨ Features

- 🎯 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

🎬 Demo

!Test Harness Screenshot

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 graphs
- demos/browser-demo.html - Simple CDN usage example with auto-initialization
- demos/example.html - Strategy-based usage example with detailed visualizations

📦 Installation

$3

`bash
npm install @axeptio/behavior-detection


or


yarn add @axeptio/behavior-detection
`

$3

`html

`

🚀 Quick Start

$3

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();
`

$3

`html








Interact with this page

Click me





`

$3

#### 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



`

🎯 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): this

Add a detection strategy with optional custom weight.

`typescript
detector.addStrategy(new Mouse(), 0.35);
`

##### removeStrategy(name: string): this

Remove a strategy by name.

`typescript
detector.removeStrategy('mouse');
`

##### setStrategyEnabled(name: string, enabled: boolean): this

Enable or disable a strategy without removing it.

`typescript
detector.setStrategyEnabled('mouse', false);
`

##### start(): void

Start all enabled strategies.

`typescript
detector.start();
`

##### stop(): void

Stop all strategies and cleanup listeners.

`typescript
detector.stop();
`

##### reset(): void

Clear all collected data without stopping.

`typescript
detector.reset();
`

##### score(options?: ScoreOptions): Promise

Calculate the human likelihood score.

`typescript
const result = await detector.score({
breakdown: true, // Include per-strategy scores
});
`

ScoreOptions:
- breakdown?: boolean - Include detailed breakdown of each strategy

ScoreResult:
`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(): boolean

Check if detector is currently tracking.

`typescript
if (detector.isActive()) {
console.log('Detector is running');
}
`

##### isPaused(): boolean

Check 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(): Record

Get event counts from all strategies.

##### getStrategyDebugInfo(): Record

Get debug information from all strategies.

##### destroy(): void

Complete 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:playwright

Test against Puppeteer

npm run test:puppeteer

Test against Selenium

npm run test:selenium

Stress 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:all

Build only ESM/CJS

npm run build

Build 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
};
}
}
``

📝 Use Cases

- 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

🎯 Detection Thresholds

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.

⚠️ Limitations

- 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.

📄 License

Proprietary © Axeptio

🙏 Acknowledgments

- 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