cyborg-hunter 0.3.0

package/src/core/monitor.js

@@ -0,0 +1,404 @@
+// src/core/monitor.js
+// Main CyborgHunter orchestrator.
+// Imports signal modules, manages lifecycle, exposes public API.
+//
+// The public API is a frozen object returned by init(). Internal state
+// is closure-scoped so participants cannot disable monitoring via console.
+
+import { createStateMachine, deepCopy } from './state-machine.js';
+import { DEFAULT_THRESHOLDS, PRESETS, VERSION } from '../shared/constants.js';
+import { validateConfig } from '../shared/validation.js';
+import { computeTrialScores, shouldScreenout as _shouldScreenout } from './scoring.js';
+import { attachClipboardSignals } from './signals/clipboard.js';
+import { attachFocusSignals, attachIdleGapSignals } from './signals/focus.js';
+import { attachMouseSignals, computeMouseMetrics } from './signals/mouse.js';
+import { attachTypingSignals, attachForeignInputSignals, computeTypingSpeed } from './signals/typing.js';
+import { attachBrowserSignals, attachElementTrace } from './signals/browser.js';
+import { injectDecoy, removeDecoyElement } from './signals/dom-protection.js';
+
+let _activeInstance = null; // Track for idempotent init
+
+/**
+ * Initialize a new CyborgHunter monitor instance.
+ * Returns a frozen monitor object with lifecycle methods.
+ *
+ * @param {Object} userConfig - Configuration object. Only participantId is required.
+ * @returns {Object} Frozen monitor instance
+ */
+export function init(userConfig) {
+  // Idempotent: if already initialized, destroy previous instance
+  if (_activeInstance) {
+    _activeInstance.destroy();
+    _activeInstance = null;
+  }
+
+  // ── Merge preset with user overrides ──
+  var presetName = userConfig.preset || "standard";
+  var preset = PRESETS[presetName];
+  if (!preset) {
+    throw new Error("IntegrityMonitor: unknown preset '" + presetName + "'. Use: permissive, standard, strict.");
+  }
+
+  // Build effective config: DEFAULT_THRESHOLDS → preset → user overrides.
+  var userScoring = userConfig.scoring || {};
+  var presetScoring = preset.scoring;
+  var mergedScoring = {
+    hard: Object.assign({}, presetScoring.hard, userScoring.hard || {}),
+    soft: Object.assign({}, presetScoring.soft, userScoring.soft || {}),
+    softScoreThreshold: userScoring.softScoreThreshold != null
+      ? userScoring.softScoreThreshold : presetScoring.softScoreThreshold
+  };
+
+  var config = {
+    participantId: userConfig.participantId || "unknown",
+    preset: presetName,
+    signals: Object.assign({}, preset.signals, userConfig.signals || {}),
+    thresholds: Object.assign({}, DEFAULT_THRESHOLDS, preset.thresholds || {}, userConfig.thresholds || {}),
+    scoring: mergedScoring,
+    screenout: Object.assign({}, preset.screenout, userConfig.screenout || {}),
+    domProtection: Object.assign({
+      preventTextSelection: false,
+      honeypotText: null,
+      logCopyAttempts: true,
+      renderStimulusAsCanvas: false
+    }, userConfig.domProtection || {}),
+    collectForPostHoc: Object.assign({
+      fullKeystrokeTimestamps: false,
+      rawMouseTrack: false,
+      responseText: false,
+      windowPositionLog: true,
+      elementTrace: false,
+      pasteDropContent: true,
+      foreignInputContent: true
+    }, userConfig.collectForPostHoc || {}),
+    decoyAnswers: userConfig.decoyAnswers || false,
+    decoyMap: userConfig.decoyMap || null,
+    decoyVisibility: userConfig.decoyVisibility || "offscreen",
+    decoyFraming: userConfig.decoyFraming || "answer-key",
+    decoyExcludeButtons: userConfig.decoyExcludeButtons || [".jspsych-btn"],
+    _debug: userConfig._debug || false
+  };
+
+  // Validate config keys — warn on typos
+  var KNOWN_KEYS = [
+    "participantId", "preset", "signals", "thresholds", "scoring",
+    "screenout", "domProtection", "collectForPostHoc", "decoyAnswers",
+    "decoyMap", "decoyVisibility", "decoyFraming", "decoyExcludeButtons",
+    "onSignal", "experimentContainer", "knownInputs", "_debug"
+  ];
+  var warnings = validateConfig(userConfig, KNOWN_KEYS);
+  warnings.forEach(function (w) { console.warn("IntegrityMonitor: " + w); });
+
+  // Freeze config
+  Object.freeze(config);
+  Object.freeze(config.signals);
+  Object.freeze(config.thresholds);
+  Object.freeze(config.scoring);
+  Object.freeze(config.scoring.hard);
+  Object.freeze(config.scoring.soft);
+  Object.freeze(config.screenout);
+
+  // ── Callback hook ──
+  var onSignal = typeof userConfig.onSignal === "function"
+    ? userConfig.onSignal : null;
+
+  // ── Experiment container ──
+  var _experimentContainerSpec = userConfig.experimentContainer || null;
+  var _experimentContainerEl = null;
+  var _knownInputsSpec = userConfig.knownInputs || null;
+
+  function resolveExperimentContainer() {
+    if (_experimentContainerEl) return _experimentContainerEl;
+    if (!_experimentContainerSpec) return null;
+    if (typeof _experimentContainerSpec === "string") {
+      _experimentContainerEl = document.querySelector(_experimentContainerSpec);
+    } else if (_experimentContainerSpec.nodeType) {
+      _experimentContainerEl = _experimentContainerSpec;
+    }
+    return _experimentContainerEl;
+  }
+
+  function isKnownInput(target) {
+    if (!target) return false;
+    if (_knownInputsSpec) {
+      try { if (target.matches(_knownInputsSpec)) return true; } catch (e) {}
+    }
+    var container = resolveExperimentContainer();
+    if (container) return container.contains(target);
+    return null;
+  }
+
+  function fireSignal(type, event, data) {
+    if (!onSignal) return;
+    try {
+      onSignal({
+        type: type,
+        event: event || null,
+        trialId: trialData ? trialData.trialId : null,
+        data: data || {}
+      });
+    } catch (e) { /* Callback errors must not break the library */ }
+  }
+
+  // ── Internal state ──
+  var sm = createStateMachine();
+  var sessionData = {
+    pasteCount: 0, copyCount: 0, dropCount: 0,
+    tabAwaySums: [], charsPerSec: [],
+    sidebarEvents: [], devToolsEvents: [],
+    aiExtensionsFound: [], keyboardShortcuts: [],
+    windowPositions: [], idleGaps: [],
+    extensionInjections: [], layoutShifts: [],
+    zoomChanges: [],
+    hardScore: {}, softScore: 0, trialsCompleted: 0
+  };
+  var trialData = null;
+  var listeners = [];
+  var trialListeners = [];
+  var intervals = [];
+
+  function transition(to) {
+    if (!sm.transition(to)) {
+      throw new Error(
+        "IntegrityMonitor: invalid transition " + sm.current + " → " + to
+      );
+    }
+  }
+
+  function addListener(target, event, handler, options) {
+    target.addEventListener(event, handler, options || false);
+    listeners.push({ target: target, event: event, handler: handler, options: options || false });
+  }
+
+  function addTrialListener(target, event, handler, options) {
+    target.addEventListener(event, handler, options || false);
+    trialListeners.push({ target: target, event: event, handler: handler, options: options || false });
+  }
+
+  function addInterval(id) {
+    intervals.push(id);
+  }
+
+  function removeTrialListeners() {
+    trialListeners.forEach(function (l) {
+      l.target.removeEventListener(l.event, l.handler, l.options);
+    });
+    trialListeners = [];
+    removeDecoyElement();
+  }
+
+  // ── Shared context for signal modules ──
+  // Signal modules receive this context object. They use it to access
+  // config, session/trial data, and register listeners. This avoids
+  // modules importing from each other (which would cause circular deps).
+  function buildSessionCtx() {
+    return {
+      config, sessionData, listeners,
+      addListener, addInterval, fireSignal,
+      getTrialData: function () { return trialData; }
+    };
+  }
+
+  function buildTrialCtx() {
+    return {
+      config, sessionData, trialData, listeners,
+      addTrialListener, addInterval, fireSignal, isKnownInput,
+      getTrialData: function () { return trialData; }
+    };
+  }
+
+  // ── Build the public API ──
+  var monitor = {
+    startSession: function () {
+      transition("session");
+      var ctx = buildSessionCtx();
+      attachBrowserSignals(ctx);
+      attachFocusSignals(ctx);
+    },
+
+    startTrial: function (opts) {
+      transition("trial");
+      opts = opts || {};
+
+      // Allow per-trial override of experiment container
+      if (opts.experimentContainer != null) {
+        _experimentContainerSpec = opts.experimentContainer;
+        _experimentContainerEl = null;
+      }
+      if (opts.knownInputs != null) {
+        _knownInputsSpec = opts.knownInputs;
+      }
+
+      trialData = {
+        trialId: opts.trialId || ("trial-" + sessionData.trialsCompleted),
+        phase: opts.phase || "default",
+        startTime: performance.now(),
+        pasteEvents: [], copyEvents: [], dropEvents: [],
+        editTimestamps: [], mouseEvents: [],
+        tabAwayEvents: [], idleGaps: [],
+        foreignInputEvents: [],
+        syntheticInsertions: []
+      };
+
+      // Decoy injection
+      removeDecoyElement();
+      if (config.decoyAnswers) {
+        var currentTrialId = trialData.trialId;
+        if (opts.decoyAnswer === false) {
+          trialData.decoy = { level: 0, source: "skipped" };
+        } else if (typeof opts.decoyAnswer === "string" && opts.decoyAnswer.length > 0) {
+          injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
+        } else if (config.decoyMap && config.decoyMap[currentTrialId]) {
+          injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
+        } else if (opts.decoyAnswer != null && opts.decoyAnswer !== false) {
+          console.warn(
+            "IntegrityMonitor: decoyAnswer must be a non-empty string, got: " +
+            typeof opts.decoyAnswer + ". Falling through to auto-detection."
+          );
+          setTimeout(function () {
+            injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
+          }, 0);
+        } else {
+          setTimeout(function () {
+            injectDecoy(opts, currentTrialId, config, trialData, function () { return trialData; });
+          }, 0);
+        }
+      } else if (opts.decoyAnswer != null) {
+        console.warn(
+          "IntegrityMonitor: decoyAnswer provided but decoyAnswers is not enabled. " +
+          "Add decoyAnswers: true to init() config."
+        );
+      }
+
+      // Attach trial-scoped signal listeners
+      var ctx = buildTrialCtx();
+      attachClipboardSignals(ctx);
+      attachTypingSignals(ctx);
+      attachMouseSignals(ctx);
+      attachIdleGapSignals(ctx);
+      attachElementTrace(ctx);
+
+      // Foreign input detection (only when container is specified)
+      if (_experimentContainerSpec || _knownInputsSpec) {
+        attachForeignInputSignals(ctx);
+      }
+    },
+
+    endTrial: function () {
+      transition("session");
+      if (!trialData) return null;
+
+      // Check if decoy element survived the trial
+      if (trialData.decoy) {
+        trialData.decoy.survivedTrial = !!document.getElementById("ch-decoy");
+      }
+
+      removeTrialListeners();
+
+      var report = deepCopy(trialData);
+      report.duration_ms = performance.now() - trialData.startTime;
+      report.libraryVersion = VERSION;
+      report.participantId = config.participantId;
+
+      // Compute typing speed
+      var cps = computeTypingSpeed(trialData.editTimestamps);
+      if (cps !== null) {
+        report.charsPerSec = cps;
+        sessionData.charsPerSec.push(cps);
+      }
+
+      // Compute mouse bot metrics
+      var mouseMetrics = computeMouseMetrics(
+        trialData.mouseEvents,
+        config.thresholds.mouseBotMinEvents
+      );
+      if (mouseMetrics) {
+        report.mouseMetrics = mouseMetrics;
+      }
+
+      // Accumulate into session
+      sessionData.trialsCompleted++;
+
+      // Two-tier scoring
+      var scores = computeTrialScores(trialData, sessionData, config, report);
+      report.trialSoftScore = scores.trialSoftScore;
+      report.trialSignals = scores.trialSignals;
+      sessionData.softScore += scores.trialSoftScore;
+      sessionData.hardScore = scores.updatedHardScore;
+
+      trialData = null;
+      return report;
+    },
+
+    getSessionScore: function () {
+      return {
+        hardScore: deepCopy(sessionData.hardScore),
+        softScore: sessionData.softScore,
+        softScoreThreshold: config.scoring.softScoreThreshold,
+        anyHardTriggered: Object.keys(sessionData.hardScore).some(function (k) {
+          return sessionData.hardScore[k].triggered;
+        }),
+        trialsCompleted: sessionData.trialsCompleted
+      };
+    },
+
+    getSessionReport: function () {
+      var report = deepCopy(sessionData);
+      // Merge in the authoritative scoring summary — same values getSessionScore() returns.
+      // Single source of truth: callers don't need to call both methods.
+      report.hardScore = deepCopy(sessionData.hardScore);
+      report.softScore = sessionData.softScore;
+      report.softScoreThreshold = config.scoring.softScoreThreshold;
+      report.anyHardTriggered = Object.keys(sessionData.hardScore).some(function (k) {
+        return sessionData.hardScore[k].triggered;
+      });
+      report.trialsCompleted = sessionData.trialsCompleted;
+      report.config = {
+        preset: config.preset,
+        participantId: config.participantId
+      };
+      report.libraryVersion = VERSION;
+      return report;
+    },
+
+    shouldScreenout: function () {
+      return _shouldScreenout(sessionData, config);
+    },
+
+    getRawData: function () {
+      return deepCopy({
+        session: sessionData,
+        config: { preset: config.preset, participantId: config.participantId },
+        libraryVersion: VERSION
+      });
+    },
+
+    getTrialSnapshot: function () {
+      if (!trialData) return null;
+      return deepCopy(trialData);
+    },
+
+    destroy: function () {
+      sm.transition("destroyed");
+      // Clean up session-scoped listeners
+      listeners.forEach(function (l) {
+        if (l.options && l.options._isMutationObserver) {
+          l.handler.disconnect();
+        } else if (l.options && l.options._isResizeObserver) {
+          l.handler.disconnect();
+        } else {
+          l.target.removeEventListener(l.event, l.handler, l.options);
+        }
+      });
+      listeners = [];
+      removeTrialListeners();
+      intervals.forEach(function (id) { clearInterval(id); });
+      intervals = [];
+      _activeInstance = null;
+    }
+  };
+
+  Object.freeze(monitor);
+  _activeInstance = monitor;
+  return monitor;
+}

package/src/core/scoring.js

@@ -0,0 +1,153 @@
+// src/core/scoring.js
+// Two-tier scoring engine:
+//   Hard signals: count-based, any one crossing its threshold = immediate screenout
+//   Soft signals: weighted accumulation with a grace period
+//
+// This module is stateless — it receives trial and session data and returns
+// updated scores. The monitor.js orchestrator manages the actual state.
+
+/**
+ * Computes trial-level scores from trial data and session counts.
+ * Returns { trialSoftScore, trialSignals, updatedHardScore }.
+ *
+ * @param {Object} trialData - The raw trial data (pasteEvents, copyEvents, etc.)
+ * @param {Object} sessionData - Session-level accumulators (pasteCount, softScore, etc.)
+ * @param {Object} config - The merged config (scoring, thresholds)
+ * @param {Object} report - The trial report being built (may have charsPerSec from typing)
+ */
+export function computeTrialScores(trialData, sessionData, config, report) {
+  var scoring = config.scoring;
+  var trialSignals = { hard: {}, soft: {} };
+  var trialSoftScore = 0;
+
+  // ── Hard signal: paste ──
+  if (scoring.hard.paste) {
+    var pasteHits = (trialData.pasteEvents || []).length;
+    trialSignals.hard.paste = {
+      trialHits: pasteHits, sessionTotal: sessionData.pasteCount,
+      countThreshold: scoring.hard.paste.countThreshold
+    };
+  }
+
+  // ── Hard signal: copy ──
+  if (scoring.hard.copy) {
+    var copyHits = (trialData.copyEvents || []).length;
+    trialSignals.hard.copy = {
+      trialHits: copyHits, sessionTotal: sessionData.copyCount,
+      countThreshold: scoring.hard.copy.countThreshold
+    };
+  }
+
+  // ── Hard signal: drop ──
+  if (scoring.hard.drop) {
+    var dropHits = (trialData.dropEvents || []).length;
+    trialSignals.hard.drop = {
+      trialHits: dropHits, sessionTotal: sessionData.dropCount,
+      countThreshold: scoring.hard.drop.countThreshold
+    };
+  }
+
+  // ── Soft signal: copy (can be both hard AND soft) ──
+  if (scoring.soft.copy) {
+    var softCopyHits = (trialData.copyEvents || []).length;
+    var softCopyCapped = scoring.soft.copy.maxPerTrial != null
+      ? Math.min(softCopyHits, scoring.soft.copy.maxPerTrial) : softCopyHits;
+    var softCopyScore = softCopyCapped * scoring.soft.copy.weight;
+    trialSoftScore += softCopyScore;
+    trialSignals.soft.copy = { hits: softCopyHits, capped: softCopyCapped, score: softCopyScore };
+  }
+
+  // ── Soft signal: tabAway ──
+  if (scoring.soft.tabAway) {
+    var tabHits = (trialData.tabAwayEvents || []).filter(function (e) {
+      return (e.duration_ms || 0) > config.thresholds.tabAwayDurationMs;
+    }).length;
+    var tabCapped = scoring.soft.tabAway.maxPerTrial != null
+      ? Math.min(tabHits, scoring.soft.tabAway.maxPerTrial) : tabHits;
+    var tabScore = tabCapped * scoring.soft.tabAway.weight;
+    trialSoftScore += tabScore;
+    trialSignals.soft.tabAway = { hits: tabHits, capped: tabCapped, score: tabScore };
+  }
+
+  // ── Soft signal: typingSpeed ──
+  if (scoring.soft.typingSpeed && report.charsPerSec != null) {
+    var speedThreshold = config.thresholds.typingSpeedCps;
+    var speedHit = report.charsPerSec > speedThreshold ? 1 : 0;
+    var speedScore = speedHit * scoring.soft.typingSpeed.weight;
+    trialSoftScore += speedScore;
+    trialSignals.soft.typingSpeed = {
+      charsPerSec: report.charsPerSec, threshold: speedThreshold,
+      hit: speedHit, score: speedScore
+    };
+  }
+
+  // ── Soft signal: sidebarEvent ──
+  // Counts sidebar events that occurred during this trial's time window.
+  if (scoring.soft.sidebarEvent) {
+    var trialSidebarHits = sessionData.sidebarEvents.filter(function (e) {
+      return e.t >= trialData.startTime && e.t <= performance.now();
+    }).length;
+    if (trialSidebarHits > 0) {
+      var sidebarScore = scoring.soft.sidebarEvent.weight;
+      trialSoftScore += sidebarScore;
+      trialSignals.soft.sidebarEvent = { hits: trialSidebarHits, score: sidebarScore };
+    }
+  }
+
+  // ── Soft signal: devTools ──
+  // Counts keyboard shortcuts detected during this trial's time window.
+  if (scoring.soft.devTools) {
+    var trialDevToolsHits = sessionData.keyboardShortcuts.filter(function (e) {
+      return e.t >= trialData.startTime && e.t <= performance.now();
+    }).length;
+    if (trialDevToolsHits > 0) {
+      var devToolsScore = scoring.soft.devTools.weight;
+      trialSoftScore += devToolsScore;
+      trialSignals.soft.devTools = { hits: trialDevToolsHits, score: devToolsScore };
+    }
+  }
+
+  // ── Soft signal: foreignInput ──
+  if (scoring.soft.foreignInput && trialData.foreignInputEvents.length > 0) {
+    var foreignHits = trialData.foreignInputEvents.length;
+    var foreignScore = scoring.soft.foreignInput.weight;
+    trialSoftScore += foreignScore;
+    trialSignals.soft.foreignInput = { hits: foreignHits, score: foreignScore };
+  }
+
+  // Update hard signal session totals
+  var updatedHardScore = {};
+  var hardKeys = Object.keys(scoring.hard);
+  for (var hk = 0; hk < hardKeys.length; hk++) {
+    var key = hardKeys[hk];
+    var counter = key === "paste" ? sessionData.pasteCount
+      : key === "copy" ? sessionData.copyCount
+      : key === "drop" ? sessionData.dropCount : 0;
+    updatedHardScore[key] = {
+      count: counter, threshold: scoring.hard[key].countThreshold,
+      triggered: counter >= scoring.hard[key].countThreshold
+    };
+  }
+
+  return { trialSoftScore, trialSignals, updatedHardScore };
+}
+
+/**
+ * Checks whether the participant should be screened out.
+ * Two-tier logic:
+ *   1. Hard signals: ANY triggered = immediate screenout (no grace period)
+ *   2. Soft signals: accumulated softScore >= threshold after grace period
+ */
+export function shouldScreenout(sessionData, config) {
+  if (!config.screenout.enabled) return false;
+
+  // Hard signals: any one triggered = screenout (no grace period)
+  var hardTriggered = Object.keys(sessionData.hardScore).some(function (k) {
+    return sessionData.hardScore[k].triggered;
+  });
+  if (hardTriggered) return true;
+
+  // Soft signals: check after grace period
+  if (sessionData.trialsCompleted < config.screenout.gracePeriodTrials) return false;
+  return sessionData.softScore >= config.scoring.softScoreThreshold;
+}