@surbee/cipher 0.1.0 → 0.2.0

package/src/types.ts

@@ -1,366 +0,0 @@
-/**
- * Cipher SDK Types
- *
- * Core type definitions for the Cipher response validation system.
- * Implementation details are hidden - the SDK communicates with Surbee's
- * secure validation engine.
- */
-
-// ============================================
-// TIER SYSTEM
-// ============================================
-
-export type CipherTier = 1 | 2 | 3 | 4 | 5;
-
-// ============================================
-// CHECK DEFINITIONS (43 checks across 6 categories)
-// ============================================
-
-export type CheckId =
-  // Tier 1 - Basic behavioral (6 checks)
-  | 'rapid_completion'
-  | 'uniform_timing'
-  | 'low_interaction'
-  | 'straight_line_answers'
-  | 'impossibly_fast'
-  | 'minimal_effort'
-  // Tier 2 - Device/automation (9 checks)
-  | 'excessive_paste'
-  | 'pointer_spikes'
-  | 'webdriver_detected'
-  | 'automation_detected'
-  | 'no_plugins'
-  | 'suspicious_user_agent'
-  | 'device_fingerprint_mismatch'
-  | 'screen_anomaly'
-  | 'suspicious_pauses'
-  // Tier 3 - Enhanced behavioral (7 checks)
-  | 'robotic_typing'
-  | 'mouse_teleporting'
-  | 'no_corrections'
-  | 'excessive_tab_switching'
-  | 'window_focus_loss'
-  | 'ai_content_basic'
-  | 'contradiction_basic'
-  // Tier 4 - Advanced (8 checks)
-  | 'hover_behavior'
-  | 'scroll_patterns'
-  | 'mouse_acceleration'
-  | 'vpn_detection'
-  | 'datacenter_ip'
-  | 'plagiarism_basic'
-  | 'quality_assessment'
-  | 'semantic_analysis'
-  // Tier 5 - Maximum (13 checks)
-  | 'ai_content_full'
-  | 'contradiction_full'
-  | 'plagiarism_full'
-  | 'fraud_ring_detection'
-  | 'answer_sharing'
-  | 'coordinated_timing'
-  | 'device_sharing'
-  | 'tor_detection'
-  | 'proxy_detection'
-  | 'timezone_validation'
-  | 'baseline_deviation'
-  | 'perplexity_analysis'
-  | 'burstiness_analysis';
-
-export interface CheckResult {
-  /** The check that was run */
-  checkId: CheckId;
-  /** Whether the check passed */
-  passed: boolean;
-  /** Suspicion score (0-1, higher = more suspicious) */
-  score: number;
-  /** Human-readable details */
-  details?: string;
-}
-
-// ============================================
-// INPUT TYPES
-// ============================================
-
-export interface ResponseInput {
-  /** The question text */
-  question: string;
-  /** The user's answer */
-  answer: string;
-  /** Question type for context */
-  questionType?: 'text' | 'multiple_choice' | 'rating' | 'scale' | 'boolean';
-  /** Time spent on this question in milliseconds */
-  responseTimeMs?: number;
-  /** Question index in the survey */
-  questionIndex?: number;
-}
-
-export interface ValidationInput {
-  /** Array of question/answer pairs */
-  responses: ResponseInput[];
-  /** Behavioral metrics from client-side tracking */
-  behavioralMetrics?: BehavioralMetrics;
-  /** Device/browser information */
-  deviceInfo?: DeviceInfo;
-  /** Survey context */
-  context?: SurveyContext;
-}
-
-export interface SurveyContext {
-  /** Survey ID for cross-respondent analysis */
-  surveyId?: string;
-  /** Expected completion time in seconds */
-  expectedDurationSeconds?: number;
-  /** Actual completion time in seconds */
-  actualDurationSeconds?: number;
-  /** Survey type for context-aware analysis */
-  surveyType?: 'nps' | 'csat' | 'research' | 'feedback' | 'quiz';
-  /** Total number of questions */
-  totalQuestions?: number;
-}
-
-// ============================================
-// BEHAVIORAL METRICS (from client tracker)
-// ============================================
-
-export interface BehavioralMetrics {
-  sessionId: string;
-  startedAt: number;
-  duration: number;
-  lastActiveAt: number;
-
-  // Mouse metrics
-  mouseMovements: MouseMovement[];
-  mouseClicks: MouseClick[];
-  mouseMovementCount: number;
-  avgMouseVelocity: number;
-
-  // Keyboard metrics
-  keystrokeDynamics: KeystrokeEvent[];
-  keypressCount: number;
-  backspaceCount: number;
-  avgKeystrokeDwell: number;
-  keystrokeVariance: number;
-
-  // Scroll metrics
-  scrollEvents: ScrollEvent[];
-  scrollEventCount: number;
-
-  // Focus metrics
-  focusEvents: FocusEvent[];
-  tabSwitchCount: number;
-  totalBlurDuration: number;
-
-  // Interaction metrics
-  pasteEvents: number;
-  copyEvents: number;
-
-  // Hover metrics (tier 3+)
-  hoverEvents: HoverEvent[];
-
-  // Question timing
-  responseTime: number[];
-  questionStartTimes: Record<string, number>;
-}
-
-export interface MouseMovement {
-  x: number;
-  y: number;
-  t: number;
-  velocity: number;
-}
-
-export interface MouseClick {
-  x: number;
-  y: number;
-  t: number;
-  hadHover: boolean;
-}
-
-export interface KeystrokeEvent {
-  key: string;
-  downAt: number;
-  upAt: number;
-  dwell: number;
-  flightTime: number;
-}
-
-export interface ScrollEvent {
-  y: number;
-  t: number;
-  velocity: number;
-}
-
-export interface FocusEvent {
-  type: 'focus' | 'blur' | 'hidden' | 'visible';
-  t: number;
-}
-
-export interface HoverEvent {
-  element: string;
-  duration: number;
-  t: number;
-}
-
-// ============================================
-// DEVICE INFO
-// ============================================
-
-export interface DeviceInfo {
-  userAgent: string;
-  platform: string;
-  language: string;
-  languages: string[];
-  timezone: string;
-  timezoneOffset: number;
-  screenWidth: number;
-  screenHeight: number;
-  screenAvailWidth: number;
-  screenAvailHeight: number;
-  colorDepth: number;
-  pixelRatio: number;
-  touchSupport: boolean;
-  maxTouchPoints: number;
-  hardwareConcurrency: number;
-  deviceMemory: number;
-  cookiesEnabled: boolean;
-  webDriver: boolean;
-  automationDetected: boolean;
-  canvasFingerprint: string | null;
-  webglVendor: string | null;
-  webglRenderer: string | null;
-  pluginCount: number;
-  collectedAt: number;
-}
-
-// ============================================
-// VALIDATION RESULT
-// ============================================
-
-export interface ValidationResult {
-  /** Overall quality score (0-1, higher = better quality) */
-  score: number;
-  /** Whether the response passed validation */
-  passed: boolean;
-  /** Recommendation for the response */
-  recommendation: 'keep' | 'review' | 'discard';
-  /** Confidence in the assessment (0-1) */
-  confidence: number;
-  /** Flags that were triggered */
-  flags: string[];
-  /** Human-readable summary analysis */
-  summary: ValidationSummary;
-  /** Detailed check results */
-  checks: CheckResult[];
-  /** Processing metadata */
-  meta: ValidationMeta;
-}
-
-export interface ValidationSummary {
-  /** Short verdict (e.g., "Likely legitimate", "Suspected bot") */
-  verdict: string;
-  /** List of issues found */
-  issues: string[];
-  /** List of positive signals */
-  positives: string[];
-  /** Actionable suggestion for the user */
-  suggestion: string;
-}
-
-export interface ValidationMeta {
-  /** Tier used for validation */
-  tier: CipherTier;
-  /** Processing time in milliseconds */
-  processingTimeMs: number;
-  /** Number of checks run */
-  checksRun: number;
-  /** Number of checks passed */
-  checksPassed: number;
-  /** Request ID for support */
-  requestId: string;
-  /** Timestamp */
-  timestamp: number;
-}
-
-// ============================================
-// CONFIGURATION
-// ============================================
-
-export interface CipherConfig {
-  /**
-   * API key from Surbee dashboard (Settings > API Keys)
-   * Format: cipher_sk_...
-   */
-  apiKey: string;
-  /**
-   * Validation tier (1-5)
-   * - Tier 1-2: Basic checks (~free)
-   * - Tier 3: Enhanced analysis
-   * - Tier 4: Advanced validation
-   * - Tier 5: Maximum accuracy
-   */
-  tier?: CipherTier;
-  /** Custom thresholds */
-  thresholds?: {
-    /** Score below this = fail (default: 0.4) */
-    fail?: number;
-    /** Score below this = review (default: 0.7) */
-    review?: number;
-  };
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom API endpoint (for enterprise/self-hosted) */
-  endpoint?: string;
-}
-
-// ============================================
-// BATCH OPERATIONS
-// ============================================
-
-export interface BatchValidationInput {
-  submissions: ValidationInput[];
-  /** Enable cross-submission fraud detection (tier 5) */
-  crossAnalysis?: boolean;
-}
-
-export interface BatchValidationResult {
-  results: ValidationResult[];
-  summary: {
-    total: number;
-    passed: number;
-    review: number;
-    failed: number;
-    avgScore: number;
-  };
-  /** Cross-submission fraud indicators (tier 5 only) */
-  fraudIndicators?: FraudIndicators;
-}
-
-export interface FraudIndicators {
-  /** Response IDs with duplicate answers */
-  duplicateAnswers: string[];
-  /** Whether coordinated timing was detected */
-  coordinatedTiming: boolean;
-  /** Whether device sharing was detected */
-  deviceSharing: boolean;
-  /** Fraud ring score (0-1) */
-  fraudRingScore: number;
-}
-
-// ============================================
-// ERROR TYPES
-// ============================================
-
-export interface CipherError {
-  code: CipherErrorCode;
-  message: string;
-  details?: Record<string, unknown>;
-}
-
-export type CipherErrorCode =
-  | 'INVALID_API_KEY'
-  | 'RATE_LIMITED'
-  | 'INSUFFICIENT_CREDITS'
-  | 'INVALID_INPUT'
-  | 'TIER_NOT_AVAILABLE'
-  | 'SERVER_ERROR'
-  | 'NETWORK_ERROR';

package/test/cipher.test.ts

@@ -1,245 +0,0 @@
-/**
- * Cipher SDK Test Suite
- *
- * Run with: npx tsx test/cipher.test.ts
- */
-
-import { Cipher } from '../src/cipher';
-import {
-  legitimateSubmission,
-  spamSubmission,
-  botSubmission,
-  straightLiningSubmission,
-  aiAssistedSubmission,
-} from './fixtures';
-
-// Colors for terminal output
-const colors = {
-  reset: '\x1b[0m',
-  green: '\x1b[32m',
-  red: '\x1b[31m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-  dim: '\x1b[2m',
-};
-
-function log(message: string, color?: keyof typeof colors) {
-  if (color) {
-    console.log(`${colors[color]}${message}${colors.reset}`);
-  } else {
-    console.log(message);
-  }
-}
-
-function printResult(name: string, result: any) {
-  const passIcon = result.passed ? '✓' : '✗';
-  const passColor = result.passed ? 'green' : 'red';
-
-  log(`\n${passIcon} ${name}`, passColor);
-  log(`  Score: ${(result.score * 100).toFixed(1)}%`, result.score >= 0.7 ? 'green' : result.score >= 0.4 ? 'yellow' : 'red');
-  log(`  Recommendation: ${result.recommendation}`, result.recommendation === 'keep' ? 'green' : result.recommendation === 'review' ? 'yellow' : 'red');
-  log(`  Confidence: ${(result.confidence * 100).toFixed(0)}%`, 'dim');
-
-  if (result.flags.length > 0) {
-    log(`  Flags: ${result.flags.join(', ')}`, 'yellow');
-  }
-
-  if (result.reasoning) {
-    log(`  Reasoning: ${result.reasoning}`, 'dim');
-  }
-
-  log(`  Processing: ${result.meta.processingTimeMs}ms | Checks: ${result.meta.checksPassed}/${result.meta.checksRun} passed`, 'dim');
-}
-
-function printCheckDetails(checks: any[]) {
-  const failed = checks.filter(c => !c.passed);
-  const suspicious = checks.filter(c => c.passed && c.score > 0.3);
-
-  if (failed.length > 0) {
-    log('\n  Failed checks:', 'red');
-    for (const check of failed) {
-      log(`    • ${check.checkId}: ${check.details || 'Failed'} (score: ${check.score.toFixed(2)})`, 'red');
-    }
-  }
-
-  if (suspicious.length > 0) {
-    log('\n  Suspicious (passed but flagged):', 'yellow');
-    for (const check of suspicious) {
-      log(`    • ${check.checkId}: ${check.details || 'Suspicious'} (score: ${check.score.toFixed(2)})`, 'yellow');
-    }
-  }
-}
-
-async function runTests() {
-  log('\n╔════════════════════════════════════════════════════════════╗', 'cyan');
-  log('║              CIPHER SDK TEST SUITE                         ║', 'cyan');
-  log('╚════════════════════════════════════════════════════════════╝', 'cyan');
-
-  // ==========================================================================
-  // TIER 1 TESTS (Basic offline)
-  // ==========================================================================
-  log('\n\n━━━ TIER 1 (Basic Offline) ━━━', 'blue');
-
-  const tier1 = new Cipher({ tier: 1, offline: true, debug: false });
-
-  log('\nTier 1 Info:', 'dim');
-  const tier1Info = tier1.getTierInfo();
-  log(`  Name: ${tier1Info.name}`, 'dim');
-  log(`  Checks: ${tier1Info.checks.length}`, 'dim');
-  log(`  Cost: $${tier1.estimateCost()} per response`, 'dim');
-
-  // Test 1.1: Legitimate submission
-  const t1_legitimate = tier1.validateSync(legitimateSubmission);
-  printResult('Legitimate Submission', t1_legitimate);
-
-  // Test 1.2: Spam submission
-  const t1_spam = tier1.validateSync(spamSubmission);
-  printResult('Spam Submission', t1_spam);
-  printCheckDetails(t1_spam.checks);
-
-  // Test 1.3: Bot submission
-  const t1_bot = tier1.validateSync(botSubmission);
-  printResult('Bot Submission', t1_bot);
-  printCheckDetails(t1_bot.checks);
-
-  // ==========================================================================
-  // TIER 2 TESTS (Advanced offline)
-  // ==========================================================================
-  log('\n\n━━━ TIER 2 (Advanced Offline) ━━━', 'blue');
-
-  const tier2 = new Cipher({ tier: 2, offline: true, debug: false });
-
-  log('\nTier 2 Info:', 'dim');
-  const tier2Info = tier2.getTierInfo();
-  log(`  Name: ${tier2Info.name}`, 'dim');
-  log(`  Checks: ${tier2Info.checks.length}`, 'dim');
-  log(`  Cost: $${tier2.estimateCost()} per response`, 'dim');
-
-  // Test 2.1: Legitimate submission
-  const t2_legitimate = tier2.validateSync(legitimateSubmission);
-  printResult('Legitimate Submission', t2_legitimate);
-
-  // Test 2.2: Straight-lining
-  const t2_straightline = tier2.validateSync(straightLiningSubmission);
-  printResult('Straight-lining Submission', t2_straightline);
-  printCheckDetails(t2_straightline.checks);
-
-  // Test 2.3: AI-assisted (paste heavy)
-  const t2_aiAssisted = tier2.validateSync(aiAssistedSubmission);
-  printResult('AI-Assisted Submission (Paste Heavy)', t2_aiAssisted);
-  printCheckDetails(t2_aiAssisted.checks);
-
-  // Test 2.4: Bot with headless device
-  const t2_bot = tier2.validateSync(botSubmission);
-  printResult('Bot with Headless Browser', t2_bot);
-  printCheckDetails(t2_bot.checks);
-
-  // ==========================================================================
-  // TIER 3-5 TESTS (AI-powered - requires API key)
-  // ==========================================================================
-  log('\n\n━━━ TIER 3-5 (AI-Powered) ━━━', 'blue');
-
-  const apiKey = process.env.ANTHROPIC_API_KEY;
-
-  if (!apiKey) {
-    log('\n⚠ ANTHROPIC_API_KEY not set - skipping AI-powered tests', 'yellow');
-    log('  Set ANTHROPIC_API_KEY environment variable to test tiers 3-5', 'dim');
-  } else {
-    // Tier 3 test
-    log('\n--- Tier 3 (Claude Sonnet 4.5) ---', 'blue');
-    const tier3 = new Cipher({ tier: 3, apiKey, debug: false });
-
-    const t3_legitimate = await tier3.validate(legitimateSubmission);
-    printResult('Legitimate Submission (Tier 3)', t3_legitimate);
-
-    const t3_spam = await tier3.validate(spamSubmission);
-    printResult('Spam Submission (Tier 3)', t3_spam);
-    printCheckDetails(t3_spam.checks);
-
-    // Tier 5 test (most thorough)
-    log('\n--- Tier 5 (Claude Opus 4.5) ---', 'blue');
-    const tier5 = new Cipher({ tier: 5, apiKey, debug: false });
-
-    log('\nTier 5 Info:', 'dim');
-    const tier5Info = tier5.getTierInfo();
-    log(`  Name: ${tier5Info.name}`, 'dim');
-    log(`  Checks: ${tier5Info.checks.length}`, 'dim');
-    log(`  Est. Cost: $${tier5.estimateCost()} per response`, 'dim');
-
-    const t5_legitimate = await tier5.validate(legitimateSubmission);
-    printResult('Legitimate Submission (Tier 5)', t5_legitimate);
-
-    const t5_bot = await tier5.validate(botSubmission);
-    printResult('Bot Submission (Tier 5)', t5_bot);
-    printCheckDetails(t5_bot.checks);
-  }
-
-  // ==========================================================================
-  // BATCH VALIDATION TEST
-  // ==========================================================================
-  log('\n\n━━━ BATCH VALIDATION ━━━', 'blue');
-
-  const batchCipher = new Cipher({ tier: 2, offline: true });
-
-  const batchResult = await batchCipher.validateBatch({
-    submissions: [
-      legitimateSubmission,
-      spamSubmission,
-      botSubmission,
-      straightLiningSubmission,
-    ],
-  });
-
-  log('\nBatch Results:', 'cyan');
-  log(`  Total: ${batchResult.summary.total}`, 'dim');
-  log(`  Passed: ${batchResult.summary.passed}`, 'green');
-  log(`  Review: ${batchResult.summary.review}`, 'yellow');
-  log(`  Failed: ${batchResult.summary.failed}`, 'red');
-  log(`  Avg Score: ${(batchResult.summary.avgScore * 100).toFixed(1)}%`, 'dim');
-
-  // ==========================================================================
-  // INDIVIDUAL CHECK IMPORTS TEST
-  // ==========================================================================
-  log('\n\n━━━ INDIVIDUAL CHECKS ━━━', 'blue');
-
-  // Import individual checks
-  const {
-    checkMinimalEffort,
-    checkStraightLining,
-    checkLowInteraction,
-    checkWebDriverDetected,
-  } = await import('../src/checks');
-
-  log('\nTesting individual check imports:', 'dim');
-
-  const minEffortResult = checkMinimalEffort(spamSubmission.responses);
-  log(`  checkMinimalEffort: ${minEffortResult.passed ? '✓' : '✗'} (score: ${minEffortResult.score.toFixed(2)})`, minEffortResult.passed ? 'green' : 'red');
-
-  const straightLineResult = checkStraightLining(straightLiningSubmission.responses);
-  log(`  checkStraightLining: ${straightLineResult.passed ? '✓' : '✗'} (score: ${straightLineResult.score.toFixed(2)})`, straightLineResult.passed ? 'green' : 'red');
-
-  const lowInteractionResult = checkLowInteraction(botSubmission.behavioralMetrics);
-  log(`  checkLowInteraction: ${lowInteractionResult.passed ? '✓' : '✗'} (score: ${lowInteractionResult.score.toFixed(2)})`, lowInteractionResult.passed ? 'green' : 'red');
-
-  const webDriverResult = checkWebDriverDetected(botSubmission.deviceInfo);
-  log(`  checkWebDriverDetected: ${webDriverResult.passed ? '✓' : '✗'} (score: ${webDriverResult.score.toFixed(2)})`, webDriverResult.passed ? 'green' : 'red');
-
-  // ==========================================================================
-  // SUMMARY
-  // ==========================================================================
-  log('\n\n╔════════════════════════════════════════════════════════════╗', 'cyan');
-  log('║                    TEST COMPLETE                           ║', 'cyan');
-  log('╚════════════════════════════════════════════════════════════╝', 'cyan');
-
-  log('\nExpected results:', 'dim');
-  log('  • Legitimate submissions should PASS with high scores', 'dim');
-  log('  • Spam/bot submissions should FAIL or be flagged for review', 'dim');
-  log('  • Straight-lining should be detected', 'dim');
-  log('  • Paste-heavy behavior should be flagged', 'dim');
-  log('  • Headless browsers should be detected', 'dim');
-  log('\n');
-}
-
-// Run tests
-runTests().catch(console.error);