@surbee/cipher 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,95 @@
+# @surbee/cipher
+
+AI-powered survey response validation — detect bots, fraud, AI-generated text,
+and low-quality responses. Score a response anywhere you collect it, not just
+inside Surbee.
+
+```bash
+pnpm add @surbee/cipher
+```
+
+## Quick start
+
+```ts
+import { Cipher } from '@surbee/cipher';
+
+const cipher = new Cipher({
+  apiKey: process.env.CIPHER_API_KEY, // cipher_sk_...
+  tier: 4,                            // 1–5, higher = more checks
+});
+
+const result = await cipher.validate({
+  responses: [
+    { question: 'Would you recommend us?', answer: 'Yes' },
+  ],
+  behavioralMetrics: tracker.getMetrics(), // optional
+  deviceInfo: tracker.getDeviceInfo(),     // optional
+});
+
+result.score;          // 0–1 (higher = better quality)
+result.recommendation; // 'keep' | 'review' | 'discard'
+result.flags;          // names of checks that fired
+```
+
+## Offline mode (tiers 1–2)
+
+Tiers 1 and 2 run fully on-device — no API key, no network. Only the offline
+checks for the tier are evaluated (AI-powered checks stay server-side).
+
+```ts
+const cipher = new Cipher({ tier: 2, offline: true }); // no apiKey needed
+
+const result = cipher.validateSync({
+  responses: [{ question: 'Rate us', answer: '4', questionType: 'rating' }],
+  deviceInfo: tracker.getDeviceInfo(),
+});
+```
+
+The decision engine combines failed checks with a noisy-OR, so a single
+high-confidence signal (a webdriver flag, straight-lining) is enough to flag a
+response — it is never averaged away by the checks that passed.
+
+## Tiers
+
+| Tier | Name     | Mode             | Notes                                   |
+| ---- | -------- | ---------------- | --------------------------------------- |
+| 1    | Basic    | offline, free    | Behavioral heuristics                   |
+| 2    | Standard | offline, free    | + device fingerprinting / automation    |
+| 3    | Enhanced | online           | + AI content quality                    |
+| 4    | Advanced | online           | + network + semantic analysis           |
+| 5    | Maximum  | online           | + cross-respondent fraud-ring detection |
+
+## API
+
+- `new Cipher(config)` — `{ apiKey?, tier?, thresholds?, offline?, debug?, endpoint? }`
+- `validate(input)` — score one response (local when `offline`, else via API)
+- `validateSync(input)` — synchronous, on-device scoring
+- `validateBatch({ submissions, crossAnalysis? })` — score many at once
+- `getTierInfo(tier?)` / `getAllTiers()` — tier metadata and check lists
+- `estimateCost(responses?)` — per-tier cost estimate (0 for tiers 1–2)
+- `checkStatus()` — verify an API key and remaining credits
+
+Individual checks are importable for custom pipelines:
+
+```ts
+import { checkWebDriverDetected, checkStraightLining } from '@surbee/cipher/checks';
+```
+
+## Result shape
+
+```ts
+{
+  score: number,                 // 0–1
+  passed: boolean,
+  recommendation: 'keep' | 'review' | 'discard',
+  confidence: number,            // 0–1
+  flags: string[],               // human-readable names of failed checks
+  summary: { verdict, issues, positives, suggestion },
+  checks: CheckResult[],         // per-check breakdown
+  meta: { tier, processingTimeMs, checksRun, checksPassed, requestId, timestamp },
+}
+```
+
+## License
+
+MIT

package/dist/checks/index.d.mts

@@ -0,0 +1,215 @@
+import { R as ResponseInput, S as SurveyContext, h as CheckResult, e as BehavioralMetrics, D as DeviceInfo } from '../types-C8t_T3bP.mjs';
+
+/**
+ * Timing-based checks
+ *
+ * Analyzes response timing patterns to detect bots and low-effort responses.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: Impossibly Fast
+ *
+ * Detects responses that were submitted faster than humanly possible.
+ * Based on reading speed + minimum typing time.
+ */
+declare function checkImpossiblyFast(responses: ResponseInput[], context?: SurveyContext): CheckResult;
+/**
+ * Check: Rapid Completion
+ *
+ * Simpler check for overall survey completion speed.
+ * Flags if completed in less than 20% of expected time.
+ */
+declare function checkRapidCompletion(responses: ResponseInput[], context?: SurveyContext): CheckResult;
+/**
+ * Check: Uniform Timing
+ *
+ * Detects robotic behavior where response times are suspiciously consistent.
+ * Humans have natural variation in response times.
+ */
+declare function checkUniformTiming(responses: ResponseInput[], metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Suspicious Pauses
+ *
+ * Detects unusual gaps in activity that might indicate:
+ * - Looking up answers
+ * - Bot waiting for external input
+ * - Copy-pasting from other sources
+ */
+declare function checkSuspiciousPauses(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Run all timing checks
+ */
+declare function runTimingChecks(responses: ResponseInput[], metrics?: BehavioralMetrics, context?: SurveyContext): CheckResult[];
+
+/**
+ * Behavioral checks
+ *
+ * Analyzes mouse, keyboard, and interaction patterns to detect bots.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: Low Interaction
+ *
+ * Detects minimal mouse/keyboard activity relative to survey duration.
+ * Bots often have very few interaction events.
+ */
+declare function checkLowInteraction(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Excessive Paste
+ *
+ * Detects heavy copy-paste behavior which might indicate:
+ * - AI-generated content being pasted
+ * - Copying from other sources
+ * - Bot automation
+ */
+declare function checkExcessivePaste(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Pointer Velocity Spikes
+ *
+ * Detects unnatural mouse movement patterns:
+ * - Teleporting (instant jumps)
+ * - Perfectly linear movement
+ * - Inhuman speeds
+ */
+declare function checkPointerSpikes(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Robotic Typing
+ *
+ * Detects uniform keystroke timing that suggests automation.
+ * Humans have natural variation in typing rhythm.
+ */
+declare function checkRoboticTyping(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Mouse Teleporting
+ *
+ * Detects large instant mouse jumps that are physically impossible.
+ */
+declare function checkMouseTeleporting(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: No Corrections
+ *
+ * Detects perfect typing with no backspaces or corrections.
+ * Humans naturally make typos and correct them.
+ */
+declare function checkNoCorrections(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Hover Behavior
+ *
+ * Analyzes mouse hover patterns before clicks.
+ * Humans typically hover before clicking; bots often don't.
+ */
+declare function checkHoverBehavior(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Scroll Patterns
+ *
+ * Analyzes scrolling behavior for signs of automation.
+ */
+declare function checkScrollPatterns(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Mouse Acceleration
+ *
+ * Analyzes natural mouse acceleration patterns.
+ * Real mice have gradual acceleration/deceleration.
+ */
+declare function checkMouseAcceleration(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Run all behavioral checks
+ */
+declare function runBehavioralChecks(metrics?: BehavioralMetrics): CheckResult[];
+
+/**
+ * Content-based checks
+ *
+ * Analyzes response content for quality and patterns.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: Minimal Effort
+ *
+ * Detects very short or low-quality text responses.
+ */
+declare function checkMinimalEffort(responses: ResponseInput[]): CheckResult;
+/**
+ * Check: Straight-Lining
+ *
+ * Detects selecting the same option repeatedly in multiple choice questions.
+ */
+declare function checkStraightLining(responses: ResponseInput[]): CheckResult;
+/**
+ * Check: Excessive Tab Switching
+ *
+ * Detects frequent tab/window changes which might indicate:
+ * - Looking up answers
+ * - Using AI to generate responses
+ * - Distracted/inattentive respondent
+ */
+declare function checkExcessiveTabSwitching(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Window Focus Loss
+ *
+ * Detects extended periods where the survey was not in focus.
+ */
+declare function checkWindowFocusLoss(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Run all content checks
+ */
+declare function runContentChecks(responses: ResponseInput[], metrics?: BehavioralMetrics): CheckResult[];
+
+/**
+ * Device-based checks
+ *
+ * Analyzes device fingerprint and browser characteristics to detect bots.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: WebDriver Detection
+ *
+ * Detects Selenium/automation tools via navigator.webdriver flag.
+ */
+declare function checkWebDriverDetected(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Automation Detection
+ *
+ * Detects headless browsers and automation frameworks.
+ */
+declare function checkAutomationDetected(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Missing Plugins
+ *
+ * Bots often have zero browser plugins, which is unusual for real browsers.
+ */
+declare function checkNoPlugins(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Suspicious User Agent
+ *
+ * Detects bot-like user agent strings.
+ */
+declare function checkSuspiciousUserAgent(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Device Fingerprint Mismatch
+ *
+ * Detects inconsistent device characteristics that suggest spoofing.
+ */
+declare function checkDeviceFingerprintMismatch(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Screen Anomaly
+ *
+ * Detects impossible or suspicious screen dimensions.
+ */
+declare function checkScreenAnomaly(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Timezone Validation
+ *
+ * Validates timezone consistency between browser and behavior.
+ */
+declare function checkTimezoneValidation(device?: DeviceInfo): CheckResult;
+/**
+ * Run all device checks
+ */
+declare function runDeviceChecks(device?: DeviceInfo): CheckResult[];
+
+export { CheckResult, checkAutomationDetected, checkDeviceFingerprintMismatch, checkExcessivePaste, checkExcessiveTabSwitching, checkHoverBehavior, checkImpossiblyFast, checkLowInteraction, checkMinimalEffort, checkMouseAcceleration, checkMouseTeleporting, checkNoCorrections, checkNoPlugins, checkPointerSpikes, checkRapidCompletion, checkRoboticTyping, checkScreenAnomaly, checkScrollPatterns, checkStraightLining, checkSuspiciousPauses, checkSuspiciousUserAgent, checkTimezoneValidation, checkUniformTiming, checkWebDriverDetected, checkWindowFocusLoss, runBehavioralChecks, runContentChecks, runDeviceChecks, runTimingChecks };

package/dist/checks/index.d.ts

@@ -0,0 +1,215 @@
+import { R as ResponseInput, S as SurveyContext, h as CheckResult, e as BehavioralMetrics, D as DeviceInfo } from '../types-C8t_T3bP.js';
+
+/**
+ * Timing-based checks
+ *
+ * Analyzes response timing patterns to detect bots and low-effort responses.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: Impossibly Fast
+ *
+ * Detects responses that were submitted faster than humanly possible.
+ * Based on reading speed + minimum typing time.
+ */
+declare function checkImpossiblyFast(responses: ResponseInput[], context?: SurveyContext): CheckResult;
+/**
+ * Check: Rapid Completion
+ *
+ * Simpler check for overall survey completion speed.
+ * Flags if completed in less than 20% of expected time.
+ */
+declare function checkRapidCompletion(responses: ResponseInput[], context?: SurveyContext): CheckResult;
+/**
+ * Check: Uniform Timing
+ *
+ * Detects robotic behavior where response times are suspiciously consistent.
+ * Humans have natural variation in response times.
+ */
+declare function checkUniformTiming(responses: ResponseInput[], metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Suspicious Pauses
+ *
+ * Detects unusual gaps in activity that might indicate:
+ * - Looking up answers
+ * - Bot waiting for external input
+ * - Copy-pasting from other sources
+ */
+declare function checkSuspiciousPauses(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Run all timing checks
+ */
+declare function runTimingChecks(responses: ResponseInput[], metrics?: BehavioralMetrics, context?: SurveyContext): CheckResult[];
+
+/**
+ * Behavioral checks
+ *
+ * Analyzes mouse, keyboard, and interaction patterns to detect bots.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: Low Interaction
+ *
+ * Detects minimal mouse/keyboard activity relative to survey duration.
+ * Bots often have very few interaction events.
+ */
+declare function checkLowInteraction(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Excessive Paste
+ *
+ * Detects heavy copy-paste behavior which might indicate:
+ * - AI-generated content being pasted
+ * - Copying from other sources
+ * - Bot automation
+ */
+declare function checkExcessivePaste(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Pointer Velocity Spikes
+ *
+ * Detects unnatural mouse movement patterns:
+ * - Teleporting (instant jumps)
+ * - Perfectly linear movement
+ * - Inhuman speeds
+ */
+declare function checkPointerSpikes(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Robotic Typing
+ *
+ * Detects uniform keystroke timing that suggests automation.
+ * Humans have natural variation in typing rhythm.
+ */
+declare function checkRoboticTyping(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Mouse Teleporting
+ *
+ * Detects large instant mouse jumps that are physically impossible.
+ */
+declare function checkMouseTeleporting(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: No Corrections
+ *
+ * Detects perfect typing with no backspaces or corrections.
+ * Humans naturally make typos and correct them.
+ */
+declare function checkNoCorrections(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Hover Behavior
+ *
+ * Analyzes mouse hover patterns before clicks.
+ * Humans typically hover before clicking; bots often don't.
+ */
+declare function checkHoverBehavior(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Scroll Patterns
+ *
+ * Analyzes scrolling behavior for signs of automation.
+ */
+declare function checkScrollPatterns(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Mouse Acceleration
+ *
+ * Analyzes natural mouse acceleration patterns.
+ * Real mice have gradual acceleration/deceleration.
+ */
+declare function checkMouseAcceleration(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Run all behavioral checks
+ */
+declare function runBehavioralChecks(metrics?: BehavioralMetrics): CheckResult[];
+
+/**
+ * Content-based checks
+ *
+ * Analyzes response content for quality and patterns.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: Minimal Effort
+ *
+ * Detects very short or low-quality text responses.
+ */
+declare function checkMinimalEffort(responses: ResponseInput[]): CheckResult;
+/**
+ * Check: Straight-Lining
+ *
+ * Detects selecting the same option repeatedly in multiple choice questions.
+ */
+declare function checkStraightLining(responses: ResponseInput[]): CheckResult;
+/**
+ * Check: Excessive Tab Switching
+ *
+ * Detects frequent tab/window changes which might indicate:
+ * - Looking up answers
+ * - Using AI to generate responses
+ * - Distracted/inattentive respondent
+ */
+declare function checkExcessiveTabSwitching(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Check: Window Focus Loss
+ *
+ * Detects extended periods where the survey was not in focus.
+ */
+declare function checkWindowFocusLoss(metrics?: BehavioralMetrics): CheckResult;
+/**
+ * Run all content checks
+ */
+declare function runContentChecks(responses: ResponseInput[], metrics?: BehavioralMetrics): CheckResult[];
+
+/**
+ * Device-based checks
+ *
+ * Analyzes device fingerprint and browser characteristics to detect bots.
+ * All checks in this file are offline (no API required).
+ */
+
+/**
+ * Check: WebDriver Detection
+ *
+ * Detects Selenium/automation tools via navigator.webdriver flag.
+ */
+declare function checkWebDriverDetected(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Automation Detection
+ *
+ * Detects headless browsers and automation frameworks.
+ */
+declare function checkAutomationDetected(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Missing Plugins
+ *
+ * Bots often have zero browser plugins, which is unusual for real browsers.
+ */
+declare function checkNoPlugins(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Suspicious User Agent
+ *
+ * Detects bot-like user agent strings.
+ */
+declare function checkSuspiciousUserAgent(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Device Fingerprint Mismatch
+ *
+ * Detects inconsistent device characteristics that suggest spoofing.
+ */
+declare function checkDeviceFingerprintMismatch(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Screen Anomaly
+ *
+ * Detects impossible or suspicious screen dimensions.
+ */
+declare function checkScreenAnomaly(device?: DeviceInfo): CheckResult;
+/**
+ * Check: Timezone Validation
+ *
+ * Validates timezone consistency between browser and behavior.
+ */
+declare function checkTimezoneValidation(device?: DeviceInfo): CheckResult;
+/**
+ * Run all device checks
+ */
+declare function runDeviceChecks(device?: DeviceInfo): CheckResult[];
+
+export { CheckResult, checkAutomationDetected, checkDeviceFingerprintMismatch, checkExcessivePaste, checkExcessiveTabSwitching, checkHoverBehavior, checkImpossiblyFast, checkLowInteraction, checkMinimalEffort, checkMouseAcceleration, checkMouseTeleporting, checkNoCorrections, checkNoPlugins, checkPointerSpikes, checkRapidCompletion, checkRoboticTyping, checkScreenAnomaly, checkScrollPatterns, checkStraightLining, checkSuspiciousPauses, checkSuspiciousUserAgent, checkTimezoneValidation, checkUniformTiming, checkWebDriverDetected, checkWindowFocusLoss, runBehavioralChecks, runContentChecks, runDeviceChecks, runTimingChecks };