@svrnsec/pulse 0.3.1 → 0.5.0

package/src/analysis/llm.js

@@ -0,0 +1,472 @@
+/**
+ * @sovereign/pulse — LLM / AI Agent Behavioral Fingerprint
+ *
+ * Detects automation driven by large language models, headless browsers
+ * controlled by AI agents (AutoGPT, CrewAI, browser-use, Playwright+LLM,
+ * Selenium+GPT-4), and synthetic user emulators.
+ *
+ * Why LLMs are detectable at the behavioral layer
+ * ───────────────────────────────────────────────
+ * A human interacting with a browser produces a signal shaped by:
+ *   – Motor control noise (Fitts' Law, signal-dependent noise in arm movement)
+ *   – Cognitive processing time (fixation → decision → motor initiation)
+ *   – Error and correction cycles (overshooting, backspacing, re-reading)
+ *   – Physiological rhythms (micro-tremor at 8–12 Hz, respiration at 0.2–0.3 Hz)
+ *
+ * An LLM agent produces:
+ *   – Think-time spikes at multiples of the model's token generation latency
+ *     (GPT-4 Turbo: ~50ms/token; Claude 3: ~30ms/token)
+ *   – Mouse paths generated by a trajectory model (no signal-dependent noise)
+ *   – Keystrokes at WPM limited by the agent's typing function, not human anatomy
+ *   – Absent micro-corrections (humans correct 7–12% of keystrokes; agents: 0%)
+ *
+ * Signals
+ * ───────
+ *   thinkTimePattern    peak in inter-event timing at known LLM token latencies
+ *   mousePathSmoothness  human paths are fractal; LLM paths are piecewise linear
+ *   correctionRate       keystrokes followed by Backspace (human: 7–12%, LLM: <1%)
+ *   pauseDistribution    human pauses are Pareto-distributed; LLM pauses are uniform
+ *   rhythmicity          presence of physiological tremor (8–12 Hz) in pointer data
+ *   eventGapCV           coefficient of variation of inter-event gaps
+ *
+ * Scoring
+ * ───────
+ * Each signal contributes a weight to an overall `aiConf` score (0–1).
+ * A score above 0.70 indicates likely AI agent. Above 0.85 is high confidence.
+ * The score is designed to be combined with the physics layer — AI agents running
+ * on real hardware (a human's machine being remote-controlled) will pass the
+ * physics check but fail the behavioral check.
+ */
+
+// ── Known LLM token latency ranges (ms per token, observed empirically) ──────
+// These appear as periodic peaks in inter-event timing when the LLM is
+// "thinking" between actions.
+const LLM_LATENCY_RANGES = [
+  { name: 'gpt-4-turbo',     minMs: 40,  maxMs:  80 },
+  { name: 'gpt-4o',          minMs: 20,  maxMs:  50 },
+  { name: 'claude-3-sonnet', minMs: 25,  maxMs:  60 },
+  { name: 'claude-3-opus',   minMs: 50,  maxMs: 120 },
+  { name: 'gemini-1.5-pro',  minMs: 30,  maxMs:  70 },
+  { name: 'llama-3-70b',     minMs: 15,  maxMs:  45 },
+];
+
+// ── Human physiological constants ─────────────────────────────────────────────
+const HUMAN_TREMOR_HZ_LO    = 8;    // micro-tremor band low (Hz)
+const HUMAN_TREMOR_HZ_HI    = 12;   // micro-tremor band high (Hz)
+const HUMAN_CORRECTION_MIN  = 0.05; // minimum human backspace rate
+const HUMAN_CORRECTION_MAX  = 0.18; // maximum human backspace rate
+
+/* ─── Public API ─────────────────────────────────────────────────────────── */
+
+/**
+ * Analyse collected behavioral signals for AI agent indicators.
+ *
+ * @param {object} signals
+ * @param {Array<{t:number, x:number, y:number}>} [signals.mouseEvents]   – {t ms, x, y}
+ * @param {Array<{t:number, key:string}>}          [signals.keyEvents]     – {t ms, key}
+ * @param {Array<number>}                          [signals.interEventGaps] – ms between any UI events
+ * @returns {LlmFingerprint}
+ */
+export function detectLlmAgent(signals = {}) {
+  const {
+    mouseEvents    = [],
+    keyEvents      = [],
+    interEventGaps = [],
+  } = signals;
+
+  const checks = [];
+
+  // ── 1. Think-time pattern ────────────────────────────────────────────────
+  if (interEventGaps.length >= 20) {
+    const thinkCheck = _analyseThinkTime(interEventGaps);
+    checks.push(thinkCheck);
+  }
+
+  // ── 2. Mouse path smoothness ─────────────────────────────────────────────
+  if (mouseEvents.length >= 30) {
+    const pathCheck = _analyseMousePath(mouseEvents);
+    checks.push(pathCheck);
+  }
+
+  // ── 3. Keystroke correction rate ─────────────────────────────────────────
+  if (keyEvents.length >= 15) {
+    const corrCheck = _analyseCorrectionRate(keyEvents);
+    checks.push(corrCheck);
+  }
+
+  // ── 4. Physiological tremor ───────────────────────────────────────────────
+  if (mouseEvents.length >= 50) {
+    const tremorCheck = _analyseTremor(mouseEvents);
+    checks.push(tremorCheck);
+  }
+
+  // ── 5. Inter-event gap distribution ──────────────────────────────────────
+  if (interEventGaps.length >= 30) {
+    const gapCheck = _analyseGapDistribution(interEventGaps);
+    checks.push(gapCheck);
+  }
+
+  if (!checks.length) {
+    return { aiConf: 0, humanConf: 0, checks: [], verdict: 'insufficient_data',
+             dataPoints: { mouseEvents: mouseEvents.length,
+                           keyEvents: keyEvents.length,
+                           gaps: interEventGaps.length } };
+  }
+
+  // Weighted average — weight by how many data points each check had
+  const totalWeight = checks.reduce((s, c) => s + c.weight, 0);
+  const aiConf      = checks.reduce((s, c) => s + c.aiScore   * c.weight, 0) / totalWeight;
+  const humanConf   = checks.reduce((s, c) => s + c.humanScore * c.weight, 0) / totalWeight;
+
+  const verdict =
+    aiConf    > 0.85 ? 'ai_agent_high_confidence'
+    : aiConf  > 0.70 ? 'ai_agent_likely'
+    : humanConf > 0.75 ? 'human_likely'
+    : 'ambiguous';
+
+  return {
+    aiConf:    +aiConf.toFixed(3),
+    humanConf: +humanConf.toFixed(3),
+    checks,
+    verdict,
+    dataPoints: {
+      mouseEvents: mouseEvents.length,
+      keyEvents:   keyEvents.length,
+      gaps:        interEventGaps.length,
+    },
+  };
+}
+
+/* ─── Signal collectors (attach to the live DOM) ─────────────────────────── */
+
+/**
+ * Create a collector that listens to DOM events and returns a snapshot
+ * of raw signals. Call `.stop()` when done collecting.
+ *
+ * @param {object} [opts]
+ * @param {EventTarget} [opts.target=window]
+ * @param {number}      [opts.maxEvents=2000]
+ * @returns {{ stop: () => LlmSignals, isCollecting: boolean }}
+ */
+export function createBehaviorCollector(opts = {}) {
+  const { target = globalThis, maxEvents = 2000 } = opts;
+
+  const mouseEvents    = [];
+  const keyEvents      = [];
+  const interEventGaps = [];
+  let   lastEventTs    = null;
+  let   collecting     = true;
+
+  const onMouse = (e) => {
+    if (!collecting || mouseEvents.length >= maxEvents) return;
+    mouseEvents.push({ t: e.timeStamp, x: e.clientX, y: e.clientY });
+    _recordGap(e.timeStamp);
+  };
+
+  const onKey = (e) => {
+    if (!collecting || keyEvents.length >= maxEvents) return;
+    keyEvents.push({ t: e.timeStamp, key: e.key });
+    _recordGap(e.timeStamp);
+  };
+
+  const onClick  = (e) => _recordGap(e.timeStamp);
+  const onScroll = ()  => _recordGap(performance.now());
+
+  function _recordGap(ts) {
+    if (lastEventTs !== null && ts > lastEventTs) {
+      interEventGaps.push(ts - lastEventTs);
+    }
+    lastEventTs = ts;
+  }
+
+  if (typeof target.addEventListener === 'function') {
+    target.addEventListener('mousemove', onMouse,  { passive: true });
+    target.addEventListener('keydown',   onKey,    { passive: true });
+    target.addEventListener('click',     onClick,  { passive: true });
+    target.addEventListener('scroll',    onScroll, { passive: true });
+  }
+
+  return {
+    get isCollecting() { return collecting; },
+    stop() {
+      collecting = false;
+      if (typeof target.removeEventListener === 'function') {
+        target.removeEventListener('mousemove', onMouse);
+        target.removeEventListener('keydown',   onKey);
+        target.removeEventListener('click',     onClick);
+        target.removeEventListener('scroll',    onScroll);
+      }
+      return { mouseEvents: [...mouseEvents],
+               keyEvents:   [...keyEvents],
+               interEventGaps: [...interEventGaps] };
+    },
+  };
+}
+
+/* ─── Internal checks ────────────────────────────────────────────────────── */
+
+function _analyseThinkTime(gaps) {
+  // Look for peaks in gap histogram that align with known LLM latency ranges
+  const histogram = _histogram(gaps, 200); // 200 bins over the gap range
+
+  let matchScore = 0;
+  const matched  = [];
+
+  for (const llm of LLM_LATENCY_RANGES) {
+    const binPower = _histogramPowerInRange(histogram, llm.minMs, llm.maxMs);
+    if (binPower > 0.15) { // >15% of all gaps fall in this LLM's latency range
+      matchScore = Math.max(matchScore, binPower);
+      matched.push(llm.name);
+    }
+  }
+
+  // Human think times follow a Pareto distribution: many short, exponentially
+  // fewer long pauses. A spike at a fixed latency range is anomalous.
+  const cv       = _cv(gaps);
+  const isPareto = cv > 1.0; // Pareto CV is always > 1
+
+  return {
+    name:       'think_time',
+    aiScore:    matchScore > 0.20 ? Math.min(1, matchScore * 3) : 0,
+    humanScore: isPareto && matchScore < 0.10 ? 0.8 : 0.2,
+    weight:     Math.min(gaps.length / 50, 1),
+    detail:     { matchedLlms: matched, peakBinPower: matchScore, isPareto },
+  };
+}
+
+function _analyseMousePath(events) {
+  // Compute path curvature at each triplet of points
+  // Human paths are fractal (self-similar at multiple scales); AI paths are
+  // smooth cubic splines or straight lines with programmatic waypoints.
+  const curvatures = [];
+  for (let i = 1; i < events.length - 1; i++) {
+    const p0 = events[i - 1];
+    const p1 = events[i];
+    const p2 = events[i + 1];
+
+    const d01 = Math.hypot(p1.x - p0.x, p1.y - p0.y);
+    const d12 = Math.hypot(p2.x - p1.x, p2.y - p1.y);
+    const d02 = Math.hypot(p2.x - p0.x, p2.y - p0.y);
+
+    // Curvature = deviation from straight line (0 = straight, 1 = sharp turn)
+    if (d01 + d12 > 0) {
+      curvatures.push(1 - (d02 / (d01 + d12)));
+    }
+  }
+
+  if (!curvatures.length) return { name: 'mouse_path', aiScore: 0, humanScore: 0.5, weight: 0.1, detail: {} };
+
+  const meanCurv = _mean(curvatures);
+  const cvCurv   = _cv(curvatures);
+
+  // Human: moderate mean curvature (0.05–0.25), high CV (varying turns)
+  // AI agent: very low mean curvature (near-straight lines), low CV (consistent)
+  const isTooSmooth  = meanCurv < 0.02 && cvCurv < 0.3;
+  const isTooRegular = cvCurv < 0.2 && meanCurv > 0 && meanCurv < 0.05;
+
+  // Velocity profile: human acceleration follows a bell curve (min jerk model)
+  // AI: piecewise constant velocity (linear interpolation between waypoints)
+  const speeds = [];
+  for (let i = 1; i < events.length; i++) {
+    const dt = events[i].t - events[i - 1].t;
+    const ds = Math.hypot(events[i].x - events[i - 1].x, events[i].y - events[i - 1].y);
+    if (dt > 0) speeds.push(ds / dt);
+  }
+  const speedCV = _cv(speeds);
+
+  // Human speed is highly variable (CV > 0.5); AI speed is consistent (CV < 0.3)
+  const aiScore = (
+    (isTooSmooth  ? 0.40 : 0) +
+    (isTooRegular ? 0.30 : 0) +
+    (speedCV < 0.25 ? 0.30 : speedCV < 0.40 ? 0.15 : 0)
+  );
+
+  return {
+    name:       'mouse_path',
+    aiScore:    Math.min(1, aiScore),
+    humanScore: aiScore < 0.2 ? 0.8 : 0.2,
+    weight:     Math.min(events.length / 100, 1),
+    detail:     { meanCurvature: +meanCurv.toFixed(4), curvatureCV: +cvCurv.toFixed(3), speedCV: +speedCV.toFixed(3) },
+  };
+}
+
+function _analyseCorrectionRate(keyEvents) {
+  const total      = keyEvents.length;
+  const backspaces = keyEvents.filter(e => e.key === 'Backspace').length;
+  const rate       = backspaces / total;
+
+  // Human: 5–18% correction rate (typos, editing)
+  // AI agent: <1% (generates correct text directly from LLM output)
+  const isTooClean = rate < HUMAN_CORRECTION_MIN;
+  const isHuman    = rate >= HUMAN_CORRECTION_MIN && rate <= HUMAN_CORRECTION_MAX;
+
+  return {
+    name:       'correction_rate',
+    aiScore:    isTooClean ? 0.75 : 0,
+    humanScore: isHuman    ? 0.85 : 0.2,
+    weight:     Math.min(total / 30, 1),
+    detail:     { correctionRate: +rate.toFixed(3), backspaces, total },
+  };
+}
+
+function _analyseTremor(mouseEvents) {
+  // Extract velocity time series and look for 8–12 Hz component
+  // Human hands exhibit involuntary micro-tremor in this band.
+  if (mouseEvents.length < 50) return { name: 'tremor', aiScore: 0, humanScore: 0.5, weight: 0.1, detail: {} };
+
+  const dt       = (mouseEvents[mouseEvents.length - 1].t - mouseEvents[0].t) / (mouseEvents.length - 1);
+  const sampleHz = dt > 0 ? 1000 / dt : 0;
+
+  if (sampleHz < 30) {
+    // Not enough temporal resolution to detect 8–12 Hz
+    return { name: 'tremor', aiScore: 0, humanScore: 0.5, weight: 0.1, detail: { reason: 'low_sample_rate' } };
+  }
+
+  // Compute x-velocity series
+  const vx = [];
+  for (let i = 1; i < mouseEvents.length; i++) {
+    const dtt = mouseEvents[i].t - mouseEvents[i - 1].t;
+    vx.push(dtt > 0 ? (mouseEvents[i].x - mouseEvents[i - 1].x) / dtt : 0);
+  }
+
+  // Rough power estimation in the tremor band using DFT on a windowed segment
+  const n        = Math.min(vx.length, 256);
+  const segment  = vx.slice(0, n);
+  const tremorPower = _bandPower(segment, sampleHz, HUMAN_TREMOR_HZ_LO, HUMAN_TREMOR_HZ_HI);
+  const totalPower  = _bandPower(segment, sampleHz, 0, sampleHz / 2);
+  const tremorRatio = totalPower > 0 ? tremorPower / totalPower : 0;
+
+  // Human: some tremor power present (ratio > 0.03)
+  // AI: tremor band is silent (ratio ≈ 0)
+  const hasTremor = tremorRatio > 0.03;
+
+  return {
+    name:       'tremor',
+    aiScore:    hasTremor ? 0 : 0.55,
+    humanScore: hasTremor ? 0.75 : 0.1,
+    weight:     0.6,
+    detail:     { tremorRatio: +tremorRatio.toFixed(4), sampleHz: +sampleHz.toFixed(1), hasTremor },
+  };
+}
+
+function _analyseGapDistribution(gaps) {
+  // Human inter-event gaps follow a heavy-tailed Pareto/lognormal distribution.
+  // AI agents produce gaps that cluster around fixed latencies (think-time = API call)
+  // making the distribution multimodal with low overall entropy.
+  const cv      = _cv(gaps);
+  const skew    = _skewness(gaps);
+  const entropy = _shannonEntropy(gaps, 50);
+
+  // Human: high CV (>0.8), right-skewed (skew > 1), decent entropy (>3 bits)
+  // AI: moderate CV, low skew, low entropy (gaps cluster at API latency values)
+  const humanScore = (
+    (cv    > 0.8 ? 0.35 : cv    > 0.5 ? 0.15 : 0) +
+    (skew  > 1.0 ? 0.35 : skew  > 0.5 ? 0.15 : 0) +
+    (entropy > 3.5 ? 0.30 : entropy > 2.5 ? 0.15 : 0)
+  );
+
+  const aiScore = (
+    (cv    < 0.4  ? 0.40 : 0) +
+    (skew  < 0.3  ? 0.30 : 0) +
+    (entropy < 2.0 ? 0.30 : 0)
+  );
+
+  return {
+    name:       'gap_distribution',
+    aiScore:    Math.min(1, aiScore),
+    humanScore: Math.min(1, humanScore),
+    weight:     Math.min(gaps.length / 60, 1),
+    detail:     { cv: +cv.toFixed(3), skewness: +skew.toFixed(3), entropyBits: +entropy.toFixed(2) },
+  };
+}
+
+/* ─── Math helpers ───────────────────────────────────────────────────────── */
+
+function _mean(arr) {
+  return arr.length ? arr.reduce((s, v) => s + v, 0) / arr.length : 0;
+}
+
+function _std(arr) {
+  const m = _mean(arr);
+  return Math.sqrt(arr.reduce((s, v) => s + (v - m) ** 2, 0) / arr.length);
+}
+
+function _cv(arr) {
+  const m = _mean(arr);
+  return m > 0 ? _std(arr) / m : 0;
+}
+
+function _skewness(arr) {
+  const m = _mean(arr);
+  const s = _std(arr);
+  if (s === 0) return 0;
+  const n = arr.length;
+  return arr.reduce((sum, v) => sum + ((v - m) / s) ** 3, 0) / n;
+}
+
+function _shannonEntropy(values, bins) {
+  if (!values.length) return 0;
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  if (max === min) return 0;
+  const width = (max - min) / bins;
+  const counts = new Array(bins).fill(0);
+  for (const v of values) {
+    const b = Math.min(bins - 1, Math.floor((v - min) / width));
+    counts[b]++;
+  }
+  const n = values.length;
+  return -counts.reduce((s, c) => {
+    if (c === 0) return s;
+    const p = c / n;
+    return s + p * Math.log2(p);
+  }, 0);
+}
+
+function _histogram(values, bins) {
+  if (!values.length) return { bins: [], min: 0, max: 0, binWidth: 0 };
+  const min = Math.min(...values);
+  const max = Math.max(...values) + 1e-9;
+  const binWidth = (max - min) / bins;
+  const counts   = new Array(bins).fill(0);
+  for (const v of values) counts[Math.floor((v - min) / binWidth)]++;
+  return { bins: counts, min, max, binWidth };
+}
+
+function _histogramPowerInRange(hist, lo, hi) {
+  const total = hist.bins.reduce((s, c) => s + c, 0);
+  if (!total) return 0;
+  let power = 0;
+  for (let i = 0; i < hist.bins.length; i++) {
+    const center = hist.min + (i + 0.5) * hist.binWidth;
+    if (center >= lo && center <= hi) power += hist.bins[i];
+  }
+  return power / total;
+}
+
+// Discrete Fourier Transform power in a frequency band (O(n²) DFT — n ≤ 256)
+function _bandPower(signal, sampleHz, fLo, fHi) {
+  const n = signal.length;
+  let power = 0;
+  for (let k = 0; k < n / 2; k++) {
+    const freq = (k * sampleHz) / n;
+    if (freq < fLo || freq > fHi) continue;
+    let re = 0, im = 0;
+    for (let t = 0; t < n; t++) {
+      const angle = (2 * Math.PI * k * t) / n;
+      re += signal[t] * Math.cos(angle);
+      im -= signal[t] * Math.sin(angle);
+    }
+    power += (re * re + im * im) / (n * n);
+  }
+  return power;
+}
+
+/**
+ * @typedef {object} LlmFingerprint
+ * @property {number}   aiConf        0–1 AI agent confidence
+ * @property {number}   humanConf     0–1 human confidence
+ * @property {object[]} checks        per-signal breakdown
+ * @property {string}   verdict
+ * @property {object}   dataPoints
+ */