cyborg-hunter 0.3.0

package/src/shared/constants.js

@@ -0,0 +1,162 @@
+// src/shared/constants.js
+// Default thresholds and preset configurations for Cyborg Hunter.
+// Single source of truth — used by both the browser library and CLI report tool.
+
+export const VERSION = "0.3.0";
+
+// Default detection thresholds shared across presets.
+// Researchers can override any value at init() time.
+export const DEFAULT_THRESHOLDS = {
+  pasteMinChars: 0,            // record ALL pastes (was 20; now 0 by default)
+  dropMinChars: 0,             // record ALL drops
+  sidebarGapPx: 100,           // outerWidth - innerWidth above this = sidebar
+  layoutCompressionPx: 20,     // innerWidth - clientWidth above scrollbar width
+  syntheticGapMs: 100,         // keydown-to-input gap above this = synthetic insertion
+  idleGapMs: 10000,            // no input for this long = idle gap
+  idleCheckIntervalMs: 5000,   // how often to check for idle gaps
+  mouseThrottleMs: 50,         // 20 Hz mouse sampling
+  mouseMaxEvents: 2000,        // safety cap per trial (configurable)
+  mouseBotMinEvents: 3,        // minimum move events for bot metrics
+  sidebarPollMs: 2000,         // sidebar + zoom check interval
+  extensionScanMs: 30000,      // AI extension DOM re-scan interval
+  windowPositionPollMs: 2000,  // screenX/screenY polling interval
+  elementTraceHz: 500,         // elementsFromPoint sampling interval (ms)
+  tabAwayDurationMs: 3000,     // tab-away longer than this counts toward soft score (and is classified as "long" in reports)
+  typingSpeedCps: 10           // chars/sec above this counts toward soft score
+};
+
+// Named detection + scoring configurations.
+// Architecture:
+//   signals    — what to COLLECT (always-on by default; disable for GDPR-sensitive signals)
+//   thresholds — detection parameters (when does an event "count"?)
+//   scoring    — two-tier screenout system:
+//                  hard: count-based, any one crossing its threshold = screenout
+//                  soft: weighted accumulation with a separate threshold
+//   screenout  — master switch + grace period
+export const PRESETS = {
+  permissive: {
+    // Collect everything, screen out nobody. For calibration/pilot studies.
+    signals: {
+      paste: true, copy: true, tabAway: true, typingSpeed: true,
+      devTools: true, aiExtensions: true, sidebarGap: true,
+      keyboardShortcuts: true, mouseTracking: true, idleGaps: true,
+      windowPosition: true, clipboardManager: true,
+      keystrokeDynamics: false  // GDPR: off by default
+    },
+    thresholds: {
+      typingSpeedCps: 15       // more lenient typing speed threshold
+    },
+    scoring: {
+      hard: {
+        paste: { countThreshold: 3 },
+        drop:  { countThreshold: 3 }
+      },
+      soft: {
+        copy:         { weight: 1, maxPerTrial: 2 },
+        tabAway:      { weight: 1, maxPerTrial: 2 },
+        typingSpeed:  { weight: 1 },
+        sidebarEvent: { weight: 1 },
+        devTools:     { weight: 1 },
+        foreignInput: { weight: 1 }
+      },
+      softScoreThreshold: 10
+    },
+    screenout: { enabled: false, gracePeriodTrials: 5 }
+  },
+  standard: {
+    // Balanced detection. Default for most studies.
+    signals: {
+      paste: true, copy: true, tabAway: true, typingSpeed: true,
+      devTools: true, aiExtensions: true, sidebarGap: true,
+      keyboardShortcuts: true, mouseTracking: true, idleGaps: true,
+      windowPosition: true, clipboardManager: true,
+      keystrokeDynamics: false  // GDPR: off by default
+    },
+    thresholds: {},  // uses DEFAULT_THRESHOLDS as-is
+    scoring: {
+      hard: {
+        paste: { countThreshold: 2 },
+        drop:  { countThreshold: 2 }
+      },
+      soft: {
+        copy:         { weight: 2, maxPerTrial: 2 },
+        tabAway:      { weight: 1, maxPerTrial: 2 },
+        typingSpeed:  { weight: 2 },
+        sidebarEvent: { weight: 3 },
+        devTools:     { weight: 1 },
+        foreignInput: { weight: 2 }
+      },
+      softScoreThreshold: 6
+    },
+    screenout: { enabled: true, gracePeriodTrials: 3 }
+  },
+  strict: {
+    // Low thresholds, all signals. For high-stakes studies.
+    signals: {
+      paste: true, copy: true, tabAway: true, typingSpeed: true,
+      devTools: true, aiExtensions: true, sidebarGap: true,
+      keyboardShortcuts: true, mouseTracking: true, idleGaps: true,
+      windowPosition: true, clipboardManager: true,
+      keystrokeDynamics: true
+    },
+    thresholds: {
+      typingSpeedCps: 8,       // stricter typing speed
+      tabAwayDurationMs: 5000, // shorter tab-away counts
+      mouseMaxEvents: 5000     // larger cap for detailed analysis
+    },
+    scoring: {
+      hard: {
+        paste: { countThreshold: 1 },
+        copy:  { countThreshold: 2 },
+        drop:  { countThreshold: 1 }
+      },
+      soft: {
+        tabAway:      { weight: 2, maxPerTrial: 1 },
+        typingSpeed:  { weight: 3 },
+        sidebarEvent: { weight: 2 },
+        devTools:     { weight: 2 },
+        foreignInput: { weight: 3 }
+      },
+      softScoreThreshold: 4
+    },
+    screenout: { enabled: true, gracePeriodTrials: 2 }
+  }
+};
+
+// AI extension selectors — used by browser detection to find known AI tools
+// in the DOM. Each entry has a human-readable name and a CSS selector.
+export const AI_SELECTORS = [
+  // ChatGPT extensions
+  { name: "ChatGPT sidebar",     sel: "chatgpt-sidebar" },
+  { name: "ChatGPT extension",   sel: "[data-chatgpt]" },
+  // Copilot browser extension (not Edge's built-in)
+  { name: "Copilot extension",   sel: "copilot-suggestions" },
+  { name: "Copilot extension",   sel: "[data-copilot]" },
+  // Gemini browser extension (not Chrome's built-in)
+  { name: "Gemini extension",    sel: "gemini-panel" },
+  // Claude browser extension
+  { name: "Claude extension",    sel: "[data-claude-extension]" },
+  // Popular AI extensions
+  { name: "Monica AI",           sel: "monica-root" },
+  { name: "Merlin AI",           sel: "merlin-root" },
+  { name: "Sider AI",            sel: "[data-sider-extension]" },
+  { name: "MaxAI",               sel: "[data-maxai]" },
+  // Generic AI assistant marker
+  { name: "AI assistant",        sel: "[data-ai-assistant]" },
+  // AI iframes (extensions embedding AI services)
+  { name: "AI iframe (OpenAI)",     sel: 'iframe[src*="chat.openai.com"]' },
+  { name: "AI iframe (Copilot)",    sel: 'iframe[src*="copilot.microsoft.com"]' },
+  { name: "AI iframe (Gemini)",     sel: 'iframe[src*="gemini.google.com"]' },
+  { name: "AI iframe (Claude)",     sel: 'iframe[src*="claude.ai"]' },
+  { name: "AI iframe (Perplexity)", sel: 'iframe[src*="perplexity.ai"]' }
+];
+
+// Benign extension tags to exclude from MutationObserver alerts.
+// These are known non-AI extensions that commonly inject DOM elements.
+export const BENIGN_TAGS = [
+  "grammarly", "lastpass", "1password", "bitwarden",
+  "dashlane", "roboform", "honey", "ublock", "adblock"
+];
+
+// Storage key prefix for localStorage/sessionStorage persistence
+export const STORAGE_PREFIX = "integrity_monitor_";

package/src/shared/schema.js

@@ -0,0 +1,56 @@
+// src/shared/schema.js
+// Defines the expected shape of integrity data for validation.
+// Used by the CLI ingest step and for documentation generation.
+
+// The fields that appear in a trial report from endTrial().
+// 'required' means the field must be present for valid integrity data.
+export const TRIAL_REPORT_FIELDS = {
+  trialId: { type: 'string', required: true },
+  phase: { type: 'string', required: false },
+  libraryVersion: { type: 'string', required: true },
+  participantId: { type: 'string', required: true },
+  startTime: { type: 'number', required: true },
+  duration_ms: { type: 'number', required: true },
+  pasteEvents: { type: 'array', required: true },
+  copyEvents: { type: 'array', required: true },
+  dropEvents: { type: 'array', required: true },
+  editTimestamps: { type: 'array', required: false },
+  charsPerSec: { type: 'number', required: false },
+  tabAwayEvents: { type: 'array', required: true },
+  idleGaps: { type: 'array', required: false },
+  mouseEvents: { type: 'array', required: false },
+  mouseMetrics: { type: 'object', required: false },
+  extensionsDetected: { type: 'array', required: false },
+  sidebarGapPx: { type: 'number', required: false },
+  foreignInputEvents: { type: 'array', required: false },
+  syntheticInsertions: { type: 'array', required: false },
+  decoy: { type: 'object', required: false },
+  trialSoftScore: { type: 'number', required: true },
+  trialSignals: { type: 'object', required: true }
+};
+
+// Default config for the CLI report tool.
+// All fields have sensible defaults — minimal config is just dataDir + filePattern.
+export const DEFAULT_CLI_CONFIG = {
+  dataDir: "./data",
+  filePattern: "*.json",
+  participantIdField: "participantId",
+  trialIdField: "trialId",
+  trialOrderField: "trialIndex",
+  integrityField: "integrity",
+  trialsPerParticipant: null,
+  platformIdField: null,
+  conditionField: null,
+  groupField: null,
+  typingSpeedThreshold_cps: 10,
+  tabAwayMinDuration_ms: 3000,
+  idleGapThreshold_ms: 10000,
+  suspiciouslyFastRT_ms: 2000,
+  scoring: null,  // uses library defaults
+  signals: null,  // all enabled
+  trajectoryGrid: "auto",
+  trajectoryTrialLabel: "trialId",
+  trajectoryResponseField: null,
+  outputDir: "./cyborg-hunter-report",
+  outputFormat: "html"
+};

package/src/shared/validation.js

@@ -0,0 +1,73 @@
+// src/shared/validation.js
+// Config validation with "did you mean?" suggestions using Levenshtein distance.
+// Used by both library init() and CLI config loading to catch typos early.
+
+import { DEFAULT_CLI_CONFIG } from './schema.js';
+import { DEFAULT_THRESHOLDS } from './constants.js';
+
+// All recognized config keys across both browser library and CLI.
+// Unknown keys trigger a warning with the closest match suggestion.
+const ALL_KNOWN_KEYS = [
+  ...Object.keys(DEFAULT_CLI_CONFIG),
+  ...Object.keys(DEFAULT_THRESHOLDS),
+  'preset', 'participantId', 'signals', 'thresholds', 'scoring',
+  'domProtection', 'collectForPostHoc', 'onSignal', 'screenout',
+  'experimentContainer', 'knownInputs', 'decoyAnswers', 'decoyMap',
+  'decoyVisibility', 'decoyFraming', 'decoyExcludeButtons',
+  'autoMonitor', 'excludeTrialTypes'
+];
+
+/**
+ * Validates a config object against known keys.
+ * Returns an array of warning strings for any unrecognized keys.
+ * Each warning includes a "did you mean?" suggestion if a close match exists.
+ */
+export function validateConfig(config, knownKeys = ALL_KNOWN_KEYS) {
+  const warnings = [];
+  Object.keys(config).forEach(key => {
+    if (!knownKeys.includes(key)) {
+      const suggestion = findClosestKey(key, knownKeys);
+      const msg = suggestion
+        ? `Unknown config key "${key}" — did you mean "${suggestion}"?`
+        : `Unknown config key "${key}"`;
+      warnings.push(msg);
+    }
+  });
+  return warnings;
+}
+
+/**
+ * Finds the closest matching key using Levenshtein distance.
+ * Returns null if no key is within edit distance 3 (too different to suggest).
+ */
+function findClosestKey(input, keys) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const key of keys) {
+    const dist = levenshtein(input.toLowerCase(), key.toLowerCase());
+    if (dist < bestDist && dist <= 3) {
+      bestDist = dist;
+      best = key;
+    }
+  }
+  return best;
+}
+
+/**
+ * Computes the Levenshtein (edit) distance between two strings.
+ * Used for "did you mean?" suggestions on misspelled config keys.
+ */
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i-1] === b[j-1]
+        ? dp[i-1][j-1]
+        : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+    }
+  }
+  return dp[m][n];
+}