@surbee/cipher 0.1.0 → 0.2.0

package/src/checks/device.ts

@@ -1,384 +0,0 @@
-/**
- * Device-based checks
- *
- * Analyzes device fingerprint and browser characteristics to detect bots.
- * All checks in this file are offline (no API required).
- */
-
-import type { CheckResult, DeviceInfo } from '../types';
-
-/**
- * Known bot user agent patterns
- */
-const BOT_USER_AGENTS = [
-  /headless/i,
-  /phantom/i,
-  /selenium/i,
-  /webdriver/i,
-  /puppeteer/i,
-  /playwright/i,
-  /crawl/i,
-  /spider/i,
-  /bot/i,
-  /scrape/i,
-  /curl/i,
-  /wget/i,
-  /python-requests/i,
-  /axios/i,
-  /node-fetch/i,
-  /go-http-client/i,
-];
-
-/**
- * Suspicious screen dimensions (commonly used by bots)
- */
-const SUSPICIOUS_SCREENS = [
-  { width: 800, height: 600 },
-  { width: 1024, height: 768 },
-  { width: 1, height: 1 },
-  { width: 0, height: 0 },
-];
-
-/**
- * Check: WebDriver Detection
- *
- * Detects Selenium/automation tools via navigator.webdriver flag.
- */
-export function checkWebDriverDetected(device?: DeviceInfo): CheckResult {
-  if (!device) {
-    return {
-      checkId: 'webdriver_detected',
-      passed: true,
-      score: 0,
-      details: 'No device info available',
-    };
-  }
-
-  if (device.webDriver === true) {
-    return {
-      checkId: 'webdriver_detected',
-      passed: false,
-      score: 1.0,
-      details: 'WebDriver automation detected',
-      data: { webDriver: true },
-    };
-  }
-
-  return {
-    checkId: 'webdriver_detected',
-    passed: true,
-    score: 0,
-    data: { webDriver: false },
-  };
-}
-
-/**
- * Check: Automation Detection
- *
- * Detects headless browsers and automation frameworks.
- */
-export function checkAutomationDetected(device?: DeviceInfo): CheckResult {
-  if (!device) {
-    return {
-      checkId: 'automation_detected',
-      passed: true,
-      score: 0,
-      details: 'No device info available',
-    };
-  }
-
-  if (device.automationDetected === true) {
-    return {
-      checkId: 'automation_detected',
-      passed: false,
-      score: 1.0,
-      details: 'Browser automation framework detected',
-      data: { automationDetected: true },
-    };
-  }
-
-  return {
-    checkId: 'automation_detected',
-    passed: true,
-    score: 0,
-    data: { automationDetected: false },
-  };
-}
-
-/**
- * Check: Missing Plugins
- *
- * Bots often have zero browser plugins, which is unusual for real browsers.
- */
-export function checkNoPlugins(device?: DeviceInfo): CheckResult {
-  if (!device) {
-    return {
-      checkId: 'no_plugins',
-      passed: true,
-      score: 0,
-      details: 'No device info available',
-    };
-  }
-
-  const { pluginCount } = device;
-
-  if (pluginCount === 0) {
-    // Could be a legitimate mobile browser or privacy-focused setup
-    // Check if it's mobile
-    const isMobile = device.touchSupport || device.maxTouchPoints > 0;
-
-    if (!isMobile) {
-      return {
-        checkId: 'no_plugins',
-        passed: true,
-        score: 0.5,
-        details: 'No browser plugins (common in automation)',
-        data: { pluginCount },
-      };
-    }
-  }
-
-  return {
-    checkId: 'no_plugins',
-    passed: true,
-    score: 0,
-    data: { pluginCount },
-  };
-}
-
-/**
- * Check: Suspicious User Agent
- *
- * Detects bot-like user agent strings.
- */
-export function checkSuspiciousUserAgent(device?: DeviceInfo): CheckResult {
-  if (!device?.userAgent) {
-    return {
-      checkId: 'suspicious_user_agent',
-      passed: true,
-      score: 0,
-      details: 'No user agent available',
-    };
-  }
-
-  const { userAgent } = device;
-
-  // Check against known bot patterns
-  for (const pattern of BOT_USER_AGENTS) {
-    if (pattern.test(userAgent)) {
-      return {
-        checkId: 'suspicious_user_agent',
-        passed: false,
-        score: 1.0,
-        details: 'Bot-like user agent detected',
-        data: { pattern: pattern.source },
-      };
-    }
-  }
-
-  // Check for empty or very short user agent
-  if (userAgent.length < 20) {
-    return {
-      checkId: 'suspicious_user_agent',
-      passed: true,
-      score: 0.5,
-      details: 'Unusually short user agent',
-      data: { length: userAgent.length },
-    };
-  }
-
-  return {
-    checkId: 'suspicious_user_agent',
-    passed: true,
-    score: 0,
-  };
-}
-
-/**
- * Check: Device Fingerprint Mismatch
- *
- * Detects inconsistent device characteristics that suggest spoofing.
- */
-export function checkDeviceFingerprintMismatch(device?: DeviceInfo): CheckResult {
-  if (!device) {
-    return {
-      checkId: 'device_fingerprint_mismatch',
-      passed: true,
-      score: 0,
-      details: 'No device info available',
-    };
-  }
-
-  const issues: string[] = [];
-
-  // Check for mismatched touch capabilities
-  if (device.touchSupport && device.maxTouchPoints === 0) {
-    issues.push('Touch support claimed but no touch points');
-  }
-
-  // Check for mismatched screen dimensions
-  if (device.screenWidth < device.screenAvailWidth || device.screenHeight < device.screenAvailHeight) {
-    issues.push('Available screen larger than total screen');
-  }
-
-  // Check for impossible hardware specs
-  if (device.hardwareConcurrency > 128) {
-    issues.push('Impossible CPU core count');
-  }
-
-  if (device.deviceMemory > 256) {
-    issues.push('Impossible memory amount');
-  }
-
-  // Check for mismatched pixel ratio
-  if (device.pixelRatio <= 0 || device.pixelRatio > 10) {
-    issues.push('Invalid pixel ratio');
-  }
-
-  if (issues.length >= 2) {
-    return {
-      checkId: 'device_fingerprint_mismatch',
-      passed: false,
-      score: 0.8,
-      details: 'Multiple device characteristic mismatches',
-      data: { issues },
-    };
-  }
-
-  if (issues.length === 1) {
-    return {
-      checkId: 'device_fingerprint_mismatch',
-      passed: true,
-      score: 0.4,
-      details: issues[0],
-      data: { issues },
-    };
-  }
-
-  return {
-    checkId: 'device_fingerprint_mismatch',
-    passed: true,
-    score: 0,
-  };
-}
-
-/**
- * Check: Screen Anomaly
- *
- * Detects impossible or suspicious screen dimensions.
- */
-export function checkScreenAnomaly(device?: DeviceInfo): CheckResult {
-  if (!device) {
-    return {
-      checkId: 'screen_anomaly',
-      passed: true,
-      score: 0,
-      details: 'No device info available',
-    };
-  }
-
-  const { screenWidth, screenHeight } = device;
-
-  // Check for impossible dimensions
-  if (screenWidth <= 0 || screenHeight <= 0) {
-    return {
-      checkId: 'screen_anomaly',
-      passed: false,
-      score: 1.0,
-      details: 'Invalid screen dimensions',
-      data: { screenWidth, screenHeight },
-    };
-  }
-
-  // Check for suspicious exact dimensions (common in bots)
-  for (const suspicious of SUSPICIOUS_SCREENS) {
-    if (screenWidth === suspicious.width && screenHeight === suspicious.height) {
-      return {
-        checkId: 'screen_anomaly',
-        passed: true,
-        score: 0.4,
-        details: 'Common automation screen size',
-        data: { screenWidth, screenHeight },
-      };
-    }
-  }
-
-  // Check for extremely unusual aspect ratios
-  const aspectRatio = screenWidth / screenHeight;
-  if (aspectRatio < 0.3 || aspectRatio > 5) {
-    return {
-      checkId: 'screen_anomaly',
-      passed: true,
-      score: 0.5,
-      details: 'Unusual screen aspect ratio',
-      data: { aspectRatio },
-    };
-  }
-
-  return {
-    checkId: 'screen_anomaly',
-    passed: true,
-    score: 0,
-  };
-}
-
-/**
- * Check: Timezone Validation
- *
- * Validates timezone consistency between browser and behavior.
- */
-export function checkTimezoneValidation(device?: DeviceInfo): CheckResult {
-  if (!device) {
-    return {
-      checkId: 'timezone_validation',
-      passed: true,
-      score: 0,
-      details: 'No device info available',
-    };
-  }
-
-  const { timezone, timezoneOffset } = device;
-
-  // Check for missing timezone data
-  if (!timezone) {
-    return {
-      checkId: 'timezone_validation',
-      passed: true,
-      score: 0.3,
-      details: 'No timezone information',
-    };
-  }
-
-  // Validate offset is reasonable (-12 to +14 hours)
-  if (timezoneOffset < -840 || timezoneOffset > 720) {
-    return {
-      checkId: 'timezone_validation',
-      passed: false,
-      score: 0.7,
-      details: 'Invalid timezone offset',
-      data: { timezoneOffset },
-    };
-  }
-
-  return {
-    checkId: 'timezone_validation',
-    passed: true,
-    score: 0,
-    data: { timezone, timezoneOffset },
-  };
-}
-
-/**
- * Run all device checks
- */
-export function runDeviceChecks(device?: DeviceInfo): CheckResult[] {
-  return [
-    checkWebDriverDetected(device),
-    checkAutomationDetected(device),
-    checkNoPlugins(device),
-    checkSuspiciousUserAgent(device),
-    checkDeviceFingerprintMismatch(device),
-    checkScreenAnomaly(device),
-    checkTimezoneValidation(device),
-  ];
-}

package/src/checks/index.ts

@@ -1,59 +0,0 @@
-/**
- * Cipher Checks - Individual importable check functions
- *
- * These can be imported individually for custom validation pipelines:
- *
- * ```typescript
- * import { checkMinimalEffort, checkStraightLining } from '@surbee/cipher/checks';
- *
- * const result1 = checkMinimalEffort(responses);
- * const result2 = checkStraightLining(responses);
- * ```
- */
-
-// Timing checks
-export {
-  checkImpossiblyFast,
-  checkRapidCompletion,
-  checkUniformTiming,
-  checkSuspiciousPauses,
-  runTimingChecks,
-} from './timing';
-
-// Behavioral checks
-export {
-  checkLowInteraction,
-  checkExcessivePaste,
-  checkPointerSpikes,
-  checkRoboticTyping,
-  checkMouseTeleporting,
-  checkNoCorrections,
-  checkHoverBehavior,
-  checkScrollPatterns,
-  checkMouseAcceleration,
-  runBehavioralChecks,
-} from './behavioral';
-
-// Content checks
-export {
-  checkMinimalEffort,
-  checkStraightLining,
-  checkExcessiveTabSwitching,
-  checkWindowFocusLoss,
-  runContentChecks,
-} from './content';
-
-// Device checks
-export {
-  checkWebDriverDetected,
-  checkAutomationDetected,
-  checkNoPlugins,
-  checkSuspiciousUserAgent,
-  checkDeviceFingerprintMismatch,
-  checkScreenAnomaly,
-  checkTimezoneValidation,
-  runDeviceChecks,
-} from './device';
-
-// Re-export types
-export type { CheckResult } from '../types';

package/src/checks/timing.ts

@@ -1,256 +0,0 @@
-/**
- * Timing-based checks
- *
- * Analyzes response timing patterns to detect bots and low-effort responses.
- * All checks in this file are offline (no API required).
- */
-
-import type { CheckResult, ResponseInput, BehavioralMetrics, SurveyContext } from '../types';
-
-/**
- * Minimum reading time per character (ms)
- * Average reading speed is ~250 words/min = ~1250 chars/min = ~48ms per char
- * We use a generous 20ms to account for fast readers
- */
-const MIN_MS_PER_CHAR = 20;
-
-/**
- * Minimum response time for any question (ms)
- */
-const MIN_RESPONSE_TIME_MS = 1000;
-
-/**
- * Check: Impossibly Fast
- *
- * Detects responses that were submitted faster than humanly possible.
- * Based on reading speed + minimum typing time.
- */
-export function checkImpossiblyFast(
-  responses: ResponseInput[],
-  context?: SurveyContext
-): CheckResult {
-  if (!context?.actualDurationSeconds || !context?.expectedDurationSeconds) {
-    // Can't check without timing data
-    return {
-      checkId: 'impossibly_fast',
-      passed: true,
-      score: 0,
-      details: 'No timing data available',
-    };
-  }
-
-  const actualMs = context.actualDurationSeconds * 1000;
-  const expectedMs = context.expectedDurationSeconds * 1000;
-
-  // Calculate minimum possible time based on content
-  let minPossibleMs = 0;
-  for (const response of responses) {
-    const questionChars = response.question.length;
-    const readingTime = questionChars * MIN_MS_PER_CHAR;
-    minPossibleMs += Math.max(readingTime, MIN_RESPONSE_TIME_MS);
-  }
-
-  // If completed faster than 30% of minimum possible time, it's suspicious
-  const suspicionThreshold = minPossibleMs * 0.3;
-
-  if (actualMs < suspicionThreshold) {
-    return {
-      checkId: 'impossibly_fast',
-      passed: false,
-      score: 1.0,
-      details: `Completed in ${context.actualDurationSeconds}s, minimum expected ${Math.round(minPossibleMs / 1000)}s`,
-      data: { actualMs, minPossibleMs, threshold: suspicionThreshold },
-    };
-  }
-
-  // Calculate a score based on how fast they were
-  // 100% of expected time = score 0, 30% = score 0.7
-  const speedRatio = actualMs / expectedMs;
-  const score = speedRatio < 1 ? Math.max(0, 1 - speedRatio) * 0.7 : 0;
-
-  return {
-    checkId: 'impossibly_fast',
-    passed: true,
-    score,
-    details: speedRatio < 0.5 ? 'Faster than average' : undefined,
-    data: { actualMs, expectedMs, speedRatio },
-  };
-}
-
-/**
- * Check: Rapid Completion
- *
- * Simpler check for overall survey completion speed.
- * Flags if completed in less than 20% of expected time.
- */
-export function checkRapidCompletion(
-  responses: ResponseInput[],
-  context?: SurveyContext
-): CheckResult {
-  if (!context?.actualDurationSeconds || !context?.expectedDurationSeconds) {
-    return {
-      checkId: 'rapid_completion',
-      passed: true,
-      score: 0,
-      details: 'No timing data available',
-    };
-  }
-
-  const ratio = context.actualDurationSeconds / context.expectedDurationSeconds;
-
-  if (ratio < 0.2) {
-    return {
-      checkId: 'rapid_completion',
-      passed: false,
-      score: 1.0,
-      details: `Completed in ${Math.round(ratio * 100)}% of expected time`,
-      data: { ratio },
-    };
-  }
-
-  if (ratio < 0.4) {
-    return {
-      checkId: 'rapid_completion',
-      passed: true,
-      score: 0.5,
-      details: 'Faster than typical',
-      data: { ratio },
-    };
-  }
-
-  return {
-    checkId: 'rapid_completion',
-    passed: true,
-    score: 0,
-    data: { ratio },
-  };
-}
-
-/**
- * Check: Uniform Timing
- *
- * Detects robotic behavior where response times are suspiciously consistent.
- * Humans have natural variation in response times.
- */
-export function checkUniformTiming(
-  responses: ResponseInput[],
-  metrics?: BehavioralMetrics
-): CheckResult {
-  const times = metrics?.responseTime || responses.map(r => r.responseTimeMs).filter(Boolean) as number[];
-
-  if (times.length < 3) {
-    return {
-      checkId: 'uniform_timing',
-      passed: true,
-      score: 0,
-      details: 'Not enough timing data',
-    };
-  }
-
-  // Calculate coefficient of variation (CV = stddev / mean)
-  const mean = times.reduce((a, b) => a + b, 0) / times.length;
-  const variance = times.reduce((sum, t) => sum + Math.pow(t - mean, 2), 0) / times.length;
-  const stddev = Math.sqrt(variance);
-  const cv = stddev / mean;
-
-  // Humans typically have CV > 0.3 for response times
-  // Bots often have CV < 0.1
-  if (cv < 0.1) {
-    return {
-      checkId: 'uniform_timing',
-      passed: false,
-      score: 1.0,
-      details: 'Response times are suspiciously uniform',
-      data: { cv, mean, stddev },
-    };
-  }
-
-  if (cv < 0.2) {
-    return {
-      checkId: 'uniform_timing',
-      passed: true,
-      score: 0.5,
-      details: 'Lower than typical timing variation',
-      data: { cv, mean, stddev },
-    };
-  }
-
-  return {
-    checkId: 'uniform_timing',
-    passed: true,
-    score: 0,
-    data: { cv, mean, stddev },
-  };
-}
-
-/**
- * Check: Suspicious Pauses
- *
- * Detects unusual gaps in activity that might indicate:
- * - Looking up answers
- * - Bot waiting for external input
- * - Copy-pasting from other sources
- */
-export function checkSuspiciousPauses(
-  metrics?: BehavioralMetrics
-): CheckResult {
-  if (!metrics?.focusEvents || metrics.focusEvents.length < 2) {
-    return {
-      checkId: 'suspicious_pauses',
-      passed: true,
-      score: 0,
-      details: 'No focus event data',
-    };
-  }
-
-  // Analyze blur durations
-  const blurEvents = metrics.focusEvents.filter(e => e.type === 'blur' || e.type === 'hidden');
-  const totalBlurTime = metrics.totalBlurDuration || 0;
-  const surveyDuration = metrics.duration || 1;
-
-  // If more than 30% of time was spent away from survey, suspicious
-  const blurRatio = totalBlurTime / surveyDuration;
-
-  if (blurRatio > 0.5) {
-    return {
-      checkId: 'suspicious_pauses',
-      passed: false,
-      score: 0.9,
-      details: `${Math.round(blurRatio * 100)}% of time spent away from survey`,
-      data: { blurRatio, totalBlurTime, blurEvents: blurEvents.length },
-    };
-  }
-
-  if (blurRatio > 0.3) {
-    return {
-      checkId: 'suspicious_pauses',
-      passed: true,
-      score: 0.5,
-      details: 'Significant time away from survey',
-      data: { blurRatio, totalBlurTime },
-    };
-  }
-
-  return {
-    checkId: 'suspicious_pauses',
-    passed: true,
-    score: 0,
-    data: { blurRatio },
-  };
-}
-
-/**
- * Run all timing checks
- */
-export function runTimingChecks(
-  responses: ResponseInput[],
-  metrics?: BehavioralMetrics,
-  context?: SurveyContext
-): CheckResult[] {
-  return [
-    checkImpossiblyFast(responses, context),
-    checkRapidCompletion(responses, context),
-    checkUniformTiming(responses, metrics),
-    checkSuspiciousPauses(metrics),
-  ];
-}