@surbee/cipher 0.1.0 → 0.2.0

package/src/checks/behavioral.ts

@@ -1,527 +0,0 @@
-/**
- * Behavioral checks
- *
- * Analyzes mouse, keyboard, and interaction patterns to detect bots.
- * All checks in this file are offline (no API required).
- */
-
-import type { CheckResult, BehavioralMetrics } from '../types';
-
-/**
- * Check: Low Interaction
- *
- * Detects minimal mouse/keyboard activity relative to survey duration.
- * Bots often have very few interaction events.
- */
-export function checkLowInteraction(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics) {
-    return {
-      checkId: 'low_interaction',
-      passed: true,
-      score: 0,
-      details: 'No behavioral data available',
-    };
-  }
-
-  const durationSeconds = (metrics.duration || 1) / 1000;
-  const totalInteractions =
-    metrics.mouseMovementCount +
-    metrics.keypressCount +
-    metrics.scrollEventCount;
-
-  // Expect at least 1 interaction per second on average
-  const interactionsPerSecond = totalInteractions / durationSeconds;
-
-  if (interactionsPerSecond < 0.1) {
-    return {
-      checkId: 'low_interaction',
-      passed: false,
-      score: 1.0,
-      details: 'Almost no user interaction detected',
-      data: { interactionsPerSecond, totalInteractions, durationSeconds },
-    };
-  }
-
-  if (interactionsPerSecond < 0.5) {
-    return {
-      checkId: 'low_interaction',
-      passed: true,
-      score: 0.6,
-      details: 'Below average interaction rate',
-      data: { interactionsPerSecond },
-    };
-  }
-
-  return {
-    checkId: 'low_interaction',
-    passed: true,
-    score: 0,
-    data: { interactionsPerSecond },
-  };
-}
-
-/**
- * Check: Excessive Paste
- *
- * Detects heavy copy-paste behavior which might indicate:
- * - AI-generated content being pasted
- * - Copying from other sources
- * - Bot automation
- */
-export function checkExcessivePaste(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics) {
-    return {
-      checkId: 'excessive_paste',
-      passed: true,
-      score: 0,
-      details: 'No behavioral data available',
-    };
-  }
-
-  const { pasteEvents, keypressCount } = metrics;
-
-  // If more pastes than manual keypresses, very suspicious
-  if (pasteEvents > 0 && keypressCount === 0) {
-    return {
-      checkId: 'excessive_paste',
-      passed: false,
-      score: 1.0,
-      details: 'All content was pasted, no typing detected',
-      data: { pasteEvents, keypressCount },
-    };
-  }
-
-  // Ratio of paste events to keypresses
-  const pasteRatio = keypressCount > 0 ? pasteEvents / keypressCount : 0;
-
-  if (pasteRatio > 0.5) {
-    return {
-      checkId: 'excessive_paste',
-      passed: false,
-      score: 0.8,
-      details: 'High paste-to-typing ratio',
-      data: { pasteRatio, pasteEvents },
-    };
-  }
-
-  if (pasteRatio > 0.2) {
-    return {
-      checkId: 'excessive_paste',
-      passed: true,
-      score: 0.4,
-      details: 'Some paste events detected',
-      data: { pasteRatio },
-    };
-  }
-
-  return {
-    checkId: 'excessive_paste',
-    passed: true,
-    score: 0,
-    data: { pasteEvents },
-  };
-}
-
-/**
- * Check: Pointer Velocity Spikes
- *
- * Detects unnatural mouse movement patterns:
- * - Teleporting (instant jumps)
- * - Perfectly linear movement
- * - Inhuman speeds
- */
-export function checkPointerSpikes(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics?.mouseMovements || metrics.mouseMovements.length < 10) {
-    return {
-      checkId: 'pointer_spikes',
-      passed: true,
-      score: 0,
-      details: 'Insufficient mouse data',
-    };
-  }
-
-  const velocities = metrics.mouseMovements
-    .map(m => m.velocity)
-    .filter(v => v > 0);
-
-  if (velocities.length === 0) {
-    return {
-      checkId: 'pointer_spikes',
-      passed: true,
-      score: 0,
-      details: 'No velocity data',
-    };
-  }
-
-  // Check for velocity spikes (inhuman speeds > 50 pixels/ms)
-  const spikeThreshold = 50;
-  const spikes = velocities.filter(v => v > spikeThreshold);
-  const spikeRatio = spikes.length / velocities.length;
-
-  if (spikeRatio > 0.3) {
-    return {
-      checkId: 'pointer_spikes',
-      passed: false,
-      score: 0.9,
-      details: 'Many unnatural mouse speed spikes detected',
-      data: { spikeRatio, spikeCount: spikes.length },
-    };
-  }
-
-  if (spikeRatio > 0.1) {
-    return {
-      checkId: 'pointer_spikes',
-      passed: true,
-      score: 0.4,
-      details: 'Some unusual mouse movements',
-      data: { spikeRatio },
-    };
-  }
-
-  return {
-    checkId: 'pointer_spikes',
-    passed: true,
-    score: 0,
-    data: { spikeRatio },
-  };
-}
-
-/**
- * Check: Robotic Typing
- *
- * Detects uniform keystroke timing that suggests automation.
- * Humans have natural variation in typing rhythm.
- */
-export function checkRoboticTyping(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics?.keystrokeDynamics || metrics.keystrokeDynamics.length < 10) {
-    return {
-      checkId: 'robotic_typing',
-      passed: true,
-      score: 0,
-      details: 'Insufficient keystroke data',
-    };
-  }
-
-  const dwellTimes = metrics.keystrokeDynamics.map(k => k.dwell).filter(d => d > 0 && d < 1000);
-
-  if (dwellTimes.length < 5) {
-    return {
-      checkId: 'robotic_typing',
-      passed: true,
-      score: 0,
-      details: 'Not enough valid keystroke data',
-    };
-  }
-
-  // Calculate coefficient of variation
-  const mean = dwellTimes.reduce((a, b) => a + b, 0) / dwellTimes.length;
-  const variance = dwellTimes.reduce((sum, t) => sum + Math.pow(t - mean, 2), 0) / dwellTimes.length;
-  const stddev = Math.sqrt(variance);
-  const cv = stddev / mean;
-
-  // Humans typically have CV > 0.25 for keystroke timing
-  if (cv < 0.08) {
-    return {
-      checkId: 'robotic_typing',
-      passed: false,
-      score: 1.0,
-      details: 'Keystroke timing is machine-like uniform',
-      data: { cv, mean, stddev },
-    };
-  }
-
-  if (cv < 0.15) {
-    return {
-      checkId: 'robotic_typing',
-      passed: true,
-      score: 0.5,
-      details: 'Lower than typical keystroke variation',
-      data: { cv },
-    };
-  }
-
-  return {
-    checkId: 'robotic_typing',
-    passed: true,
-    score: 0,
-    data: { cv },
-  };
-}
-
-/**
- * Check: Mouse Teleporting
- *
- * Detects large instant mouse jumps that are physically impossible.
- */
-export function checkMouseTeleporting(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics?.mouseMovements || metrics.mouseMovements.length < 5) {
-    return {
-      checkId: 'mouse_teleporting',
-      passed: true,
-      score: 0,
-      details: 'Insufficient mouse data',
-    };
-  }
-
-  let teleportCount = 0;
-  const movements = metrics.mouseMovements;
-
-  for (let i = 1; i < movements.length; i++) {
-    const prev = movements[i - 1];
-    const curr = movements[i];
-    const dx = curr.x - prev.x;
-    const dy = curr.y - prev.y;
-    const distance = Math.sqrt(dx * dx + dy * dy);
-    const dt = curr.t - prev.t;
-
-    // If moved > 500px in < 10ms, it's a teleport
-    if (distance > 500 && dt < 10) {
-      teleportCount++;
-    }
-  }
-
-  const teleportRatio = teleportCount / movements.length;
-
-  if (teleportRatio > 0.2) {
-    return {
-      checkId: 'mouse_teleporting',
-      passed: false,
-      score: 0.9,
-      details: 'Frequent mouse teleportation detected',
-      data: { teleportCount, teleportRatio },
-    };
-  }
-
-  if (teleportRatio > 0.05) {
-    return {
-      checkId: 'mouse_teleporting',
-      passed: true,
-      score: 0.4,
-      details: 'Some mouse teleportation detected',
-      data: { teleportCount },
-    };
-  }
-
-  return {
-    checkId: 'mouse_teleporting',
-    passed: true,
-    score: 0,
-    data: { teleportCount },
-  };
-}
-
-/**
- * Check: No Corrections
- *
- * Detects perfect typing with no backspaces or corrections.
- * Humans naturally make typos and correct them.
- */
-export function checkNoCorrections(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics || metrics.keypressCount < 20) {
-    return {
-      checkId: 'no_corrections',
-      passed: true,
-      score: 0,
-      details: 'Insufficient typing data',
-    };
-  }
-
-  const { backspaceCount, keypressCount } = metrics;
-  const correctionRatio = backspaceCount / keypressCount;
-
-  // Typical humans have ~5-15% backspace rate
-  if (backspaceCount === 0 && keypressCount > 50) {
-    return {
-      checkId: 'no_corrections',
-      passed: false,
-      score: 0.8,
-      details: 'No typing corrections despite significant text entry',
-      data: { backspaceCount, keypressCount },
-    };
-  }
-
-  if (correctionRatio < 0.01 && keypressCount > 30) {
-    return {
-      checkId: 'no_corrections',
-      passed: true,
-      score: 0.5,
-      details: 'Very few typing corrections',
-      data: { correctionRatio },
-    };
-  }
-
-  return {
-    checkId: 'no_corrections',
-    passed: true,
-    score: 0,
-    data: { correctionRatio },
-  };
-}
-
-/**
- * Check: Hover Behavior
- *
- * Analyzes mouse hover patterns before clicks.
- * Humans typically hover before clicking; bots often don't.
- */
-export function checkHoverBehavior(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics?.mouseClicks || metrics.mouseClicks.length < 3) {
-    return {
-      checkId: 'hover_behavior',
-      passed: true,
-      score: 0,
-      details: 'Insufficient click data',
-    };
-  }
-
-  const clicksWithHover = metrics.mouseClicks.filter(c => c.hadHover);
-  const hoverRatio = clicksWithHover.length / metrics.mouseClicks.length;
-
-  // Humans typically hover before ~70%+ of clicks
-  if (hoverRatio < 0.2) {
-    return {
-      checkId: 'hover_behavior',
-      passed: false,
-      score: 0.8,
-      details: 'Clicks without natural hover behavior',
-      data: { hoverRatio, totalClicks: metrics.mouseClicks.length },
-    };
-  }
-
-  if (hoverRatio < 0.4) {
-    return {
-      checkId: 'hover_behavior',
-      passed: true,
-      score: 0.4,
-      details: 'Lower than typical hover-before-click rate',
-      data: { hoverRatio },
-    };
-  }
-
-  return {
-    checkId: 'hover_behavior',
-    passed: true,
-    score: 0,
-    data: { hoverRatio },
-  };
-}
-
-/**
- * Check: Scroll Patterns
- *
- * Analyzes scrolling behavior for signs of automation.
- */
-export function checkScrollPatterns(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics?.scrollEvents || metrics.scrollEvents.length < 5) {
-    return {
-      checkId: 'scroll_patterns',
-      passed: true,
-      score: 0,
-      details: 'Insufficient scroll data',
-    };
-  }
-
-  const velocities = metrics.scrollEvents.map(s => Math.abs(s.velocity)).filter(v => v > 0);
-
-  if (velocities.length < 3) {
-    return {
-      checkId: 'scroll_patterns',
-      passed: true,
-      score: 0,
-    };
-  }
-
-  // Check for uniform scroll velocity (robotic)
-  const mean = velocities.reduce((a, b) => a + b, 0) / velocities.length;
-  const variance = velocities.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / velocities.length;
-  const cv = Math.sqrt(variance) / mean;
-
-  if (cv < 0.1) {
-    return {
-      checkId: 'scroll_patterns',
-      passed: false,
-      score: 0.7,
-      details: 'Unnaturally uniform scroll pattern',
-      data: { cv },
-    };
-  }
-
-  return {
-    checkId: 'scroll_patterns',
-    passed: true,
-    score: 0,
-    data: { cv },
-  };
-}
-
-/**
- * Check: Mouse Acceleration
- *
- * Analyzes natural mouse acceleration patterns.
- * Real mice have gradual acceleration/deceleration.
- */
-export function checkMouseAcceleration(metrics?: BehavioralMetrics): CheckResult {
-  if (!metrics?.mouseMovements || metrics.mouseMovements.length < 20) {
-    return {
-      checkId: 'mouse_acceleration',
-      passed: true,
-      score: 0,
-      details: 'Insufficient mouse data',
-    };
-  }
-
-  const velocities = metrics.mouseMovements.map(m => m.velocity).filter(v => v > 0);
-
-  if (velocities.length < 10) {
-    return {
-      checkId: 'mouse_acceleration',
-      passed: true,
-      score: 0,
-    };
-  }
-
-  // Calculate acceleration (change in velocity)
-  const accelerations: number[] = [];
-  for (let i = 1; i < velocities.length; i++) {
-    accelerations.push(Math.abs(velocities[i] - velocities[i - 1]));
-  }
-
-  // Check if acceleration is too uniform
-  const meanAcc = accelerations.reduce((a, b) => a + b, 0) / accelerations.length;
-  const varianceAcc = accelerations.reduce((sum, a) => sum + Math.pow(a - meanAcc, 2), 0) / accelerations.length;
-  const cvAcc = Math.sqrt(varianceAcc) / meanAcc;
-
-  if (cvAcc < 0.2) {
-    return {
-      checkId: 'mouse_acceleration',
-      passed: true,
-      score: 0.5,
-      details: 'Lower than typical acceleration variation',
-      data: { cvAcc },
-    };
-  }
-
-  return {
-    checkId: 'mouse_acceleration',
-    passed: true,
-    score: 0,
-    data: { cvAcc },
-  };
-}
-
-/**
- * Run all behavioral checks
- */
-export function runBehavioralChecks(metrics?: BehavioralMetrics): CheckResult[] {
-  return [
-    checkLowInteraction(metrics),
-    checkExcessivePaste(metrics),
-    checkPointerSpikes(metrics),
-    checkRoboticTyping(metrics),
-    checkMouseTeleporting(metrics),
-    checkNoCorrections(metrics),
-    checkHoverBehavior(metrics),
-    checkScrollPatterns(metrics),
-    checkMouseAcceleration(metrics),
-  ];
-}