@toffee-at/sdk 0.1.0

package/src/detect/index.ts

@@ -0,0 +1,202 @@
+import type { DetectorResult, DetectionOutput, RiskTier } from './types';
+import { detectUserAgent } from './user-agent';
+import { detectHeadless } from './headless';
+import { detectAutomation } from './automation';
+import { detectBehavioral } from './behavioral';
+import { detectNavigator } from './navigator';
+import { detectFingerprint } from './fingerprint';
+
+export type { DetectorResult, DetectionOutput } from './types';
+
+/**
+ * Per-detector LLR ranges.
+ *
+ * Key insight: a rawScore of 0 means different things for different detectors.
+ * - behavioral 0 = "observed human mouse/scroll/keyboard" → strong human evidence (LLR = -3.0)
+ * - user-agent 0 = "no known bot UA match" → weak signal (many stealthy bots also score 0)
+ * - headless 0 = "no headless indicators" → mild human evidence
+ *
+ * [llrAtZero, llrAt100]
+ */
+const DETECTOR_LLR_RANGE: Record<string, [number, number]> = {
+  'user-agent':  [-0.1, 5.0],  // UA match is definitive, but absence means almost nothing
+  'headless':    [-0.2, 4.0],  // Headless signals are strong, absence is mild
+  'automation':  [-0.1, 5.0],  // Globals are definitive, absence means nothing
+  'navigator':   [-0.1, 3.5],  // Consistency checks — clean is expected
+  'fingerprint': [-0.1, 3.5],  // Canvas/WebGL — clean is expected
+  'behavioral':  [-2.5, 6.0],  // The most important detector for extension-based agents
+};
+
+function rawScoreToLLR(detector: string, rawScore: number): number {
+  const [llrZero, llrHundred] = DETECTOR_LLR_RANGE[detector] ?? [-0.5, 4.0];
+  // Linear interpolation from [0 → llrZero] to [100 → llrHundred]
+  return llrZero + (rawScore / 100) * (llrHundred - llrZero);
+}
+
+/**
+ * Log-odds Bayesian fusion.
+ * Combines independent evidence from multiple detectors into a single probability.
+ */
+function bayesianFusion(results: DetectorResult[]): DetectionOutput {
+  // Prior: assume 15% bot traffic (slightly higher than average given the agent era)
+  const PRIOR_LOG_ODDS = Math.log(0.15 / 0.85); // ≈ -1.735
+
+  let logOddsPosterior = PRIOR_LOG_ODDS;
+
+  const signalDetails = results.map((r) => {
+    const llr = rawScoreToLLR(r.detector, r.rawScore);
+    logOddsPosterior += llr;
+    return {
+      detector: r.detector,
+      fired: r.rawScore > 0,
+      llr,
+      rawScore: r.rawScore,
+      evidence: r.signals,
+    };
+  });
+
+  // Convert log-odds to probability
+  let probability = 1 / (1 + Math.exp(-logOddsPosterior));
+
+  // Apply boosting rules for high-confidence combinations
+  const allSignals = results.flatMap((r) => r.signals);
+
+  // Webdriver + no mouse → almost certainly agent
+  const hasWebdriver = allSignals.includes('webdriver-flag') || allSignals.includes('webdriver');
+  const noMouse = allSignals.includes('no-mouse-events');
+  const noScroll = allSignals.includes('no-scroll-events');
+
+  if (hasWebdriver && noMouse) {
+    probability = Math.max(probability, 0.90);
+  } else if (hasWebdriver && noScroll) {
+    probability = Math.max(probability, 0.80);
+  }
+
+  // Extension-based agent detection: behavioral pattern combos
+  const hasTeleportClicks = allSignals.some((s) => s.startsWith('teleport-clicks:'));
+  const hasMinimalApproach = allSignals.some((s) => s.startsWith('minimal-approach-path:'));
+  const hasLowEntropy = allSignals.some((s) => s.startsWith('low-trajectory-entropy:'));
+  const hasMediumEntropy = allSignals.some((s) => s.startsWith('medium-trajectory-entropy:'));
+  const hasNoJitter = allSignals.includes('no-micro-jitter');
+  const hasSparseEvents = allSignals.some((s) => s.startsWith('very-sparse-mouse-events:') || s.startsWith('sparse-mouse-events:'));
+  const hasTeleportation = allSignals.some((s) => s.startsWith('mouse-teleportation:'));
+  const hasLowPointsPerClick = allSignals.some((s) => s.startsWith('low-points-per-click:'));
+
+  // Teleportation + sparse events = classic extension-based agent pattern
+  if (hasTeleportation && hasSparseEvents) {
+    probability = Math.max(probability, 0.85);
+  }
+  if (hasTeleportClicks && hasNoJitter) {
+    probability = Math.max(probability, 0.85);
+  }
+  if (hasTeleportClicks && (hasLowEntropy || hasMediumEntropy)) {
+    probability = Math.max(probability, 0.80);
+  }
+  if (hasMinimalApproach && hasNoJitter) {
+    probability = Math.max(probability, 0.80);
+  }
+  // Sparse events alone with low entropy is very suspicious
+  if (hasSparseEvents && (hasLowEntropy || hasMediumEntropy) && hasTeleportation) {
+    probability = Math.max(probability, 0.90);
+  }
+  // Low points per click + sparse events = definitive agent pattern
+  if (hasLowPointsPerClick && hasSparseEvents) {
+    probability = Math.max(probability, 0.85);
+  }
+
+  // Software renderer is a strong headless signal
+  const hasSoftwareRenderer = allSignals.some((s) => s.startsWith('software-renderer:'));
+  if (hasSoftwareRenderer) {
+    probability = Math.max(probability, 0.80);
+  }
+
+  // Clamp probability
+  probability = Math.max(0, Math.min(1, probability));
+
+  // Determine risk tier
+  let riskTier: RiskTier;
+  if (probability >= 0.95) riskTier = 'definite-bot';
+  else if (probability >= 0.80) riskTier = 'likely-bot';
+  else if (probability >= 0.50) riskTier = 'suspicious';
+  else if (probability >= 0.20) riskTier = 'likely-human';
+  else riskTier = 'definite-human';
+
+  // Legacy score (0-100) for backwards compatibility
+  const legacyScore = Math.round(probability * 100);
+
+  const isAgent = probability >= 0.50;
+
+  return {
+    score: legacyScore,
+    probability,
+    riskTier,
+    isAgent,
+    results,
+    signals: signalDetails,
+    classification: {
+      classification: isAgent ? 'bot' : 'human',
+      probabilities: { human: 1 - probability, bot: probability, agent: 0 },
+      source: 'heuristic',
+    },
+  };
+}
+
+export function runSync(): DetectionOutput {
+  const results = [
+    detectUserAgent(),
+    detectHeadless(),
+    detectAutomation(),
+    detectNavigator(),
+    detectFingerprint(),
+  ];
+  return bayesianFusion(results);
+}
+
+export async function runFull(): Promise<DetectionOutput> {
+  const syncResults = [
+    detectUserAgent(),
+    detectHeadless(),
+    detectAutomation(),
+    detectNavigator(),
+    detectFingerprint(),
+  ];
+  const behavioral = await detectBehavioral();
+  return bayesianFusion([...syncResults, behavioral]);
+}
+
+export function applyModelClassification(
+  output: DetectionOutput,
+  modelResult: { classification: string; probabilities: { human: number; bot: number; agent: number } },
+): DetectionOutput {
+  const prob = 1 - modelResult.probabilities.human;
+  let riskTier: RiskTier;
+  if (prob >= 0.95) riskTier = 'definite-bot';
+  else if (prob >= 0.80) riskTier = 'likely-bot';
+  else if (prob >= 0.50) riskTier = 'suspicious';
+  else if (prob >= 0.20) riskTier = 'likely-human';
+  else riskTier = 'definite-human';
+
+  return {
+    ...output,
+    probability: prob,
+    riskTier,
+    isAgent: modelResult.classification !== 'human',
+    classification: {
+      classification: modelResult.classification as 'human' | 'bot' | 'agent',
+      probabilities: modelResult.probabilities,
+      source: 'model',
+    },
+  };
+}
+
+/** Run sync detectors + an externally-provided behavioral result (from persistent monitor) */
+export function runWithBehavioral(behavioral: import('./types').DetectorResult): DetectionOutput {
+  const syncResults = [
+    detectUserAgent(),
+    detectHeadless(),
+    detectAutomation(),
+    detectNavigator(),
+    detectFingerprint(),
+  ];
+  return bayesianFusion([...syncResults, behavioral]);
+}

package/src/detect/navigator.ts

@@ -0,0 +1,102 @@
+import type { DetectorResult } from './types';
+
+/**
+ * Navigator/API consistency checks.
+ * Catches bots that spoof user-agent but forget to sync Client Hints,
+ * platform, and browser-specific APIs.
+ */
+export function detectNavigator(): DetectorResult {
+  let score = 0;
+  const signals: string[] = [];
+  const ua = navigator.userAgent;
+
+  // 1. Client Hints mismatch: UA says one platform but userAgentData says another
+  try {
+    const uaData = (navigator as any).userAgentData;
+    if (uaData) {
+      const uaPlatform = uaData.platform?.toLowerCase() || '';
+      const claimsMac = /Macintosh|Mac OS X/i.test(ua);
+      const claimsWindows = /Windows/i.test(ua);
+      const claimsLinux = /Linux/i.test(ua) && !/Android/i.test(ua);
+
+      if (claimsMac && uaPlatform && uaPlatform !== 'macos' && uaPlatform !== 'mac os x') {
+        score += 30;
+        signals.push('client-hints-platform-mismatch');
+      } else if (claimsWindows && uaPlatform && uaPlatform !== 'windows') {
+        score += 30;
+        signals.push('client-hints-platform-mismatch');
+      } else if (claimsLinux && uaPlatform && uaPlatform !== 'linux') {
+        score += 30;
+        signals.push('client-hints-platform-mismatch');
+      }
+    } else if (/Chrome\/\d/.test(ua) && parseInt(ua.match(/Chrome\/(\d+)/)?.[1] || '0') >= 90) {
+      // Chrome 90+ should have userAgentData
+      score += 15;
+      signals.push('missing-user-agent-data');
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  // 2. Hardware concurrency: containerized/headless often has 1 or undefined
+  if (navigator.hardwareConcurrency !== undefined && navigator.hardwareConcurrency <= 1) {
+    score += 15;
+    signals.push('low-hardware-concurrency');
+  }
+
+  // 3. Device memory: missing in many headless setups
+  if (/Chrome/.test(ua) && (navigator as any).deviceMemory === undefined) {
+    score += 10;
+    signals.push('missing-device-memory');
+  }
+
+  // 4. Connection API: real browsers typically have this
+  if (/Chrome/.test(ua) && !(navigator as any).connection) {
+    score += 10;
+    signals.push('missing-connection-api');
+  }
+
+  // 5. Platform inconsistency: UA claims one OS but navigator.platform says another
+  try {
+    const platform = navigator.platform?.toLowerCase() || '';
+    const claimsMac = /Macintosh|Mac OS X/i.test(ua);
+    const claimsWindows = /Windows/i.test(ua);
+
+    if (claimsMac && platform && !platform.includes('mac')) {
+      score += 25;
+      signals.push('platform-ua-mismatch');
+    } else if (claimsWindows && platform && !platform.includes('win')) {
+      score += 25;
+      signals.push('platform-ua-mismatch');
+    }
+  } catch {
+    // Ignore
+  }
+
+  // 6. Screen/display anomalies (moved here from headless for better grouping)
+  // outerHeight === innerHeight means no browser chrome (tabs, bookmarks, address bar)
+  if (window.outerHeight > 0 && window.innerHeight > 0 &&
+      window.outerHeight === window.innerHeight) {
+    score += 10;
+    signals.push('no-browser-chrome');
+  }
+
+  // screen.width === screen.availWidth means no OS taskbar
+  if (screen.width === screen.availWidth && screen.height === screen.availHeight &&
+      screen.width > 0) {
+    score += 5;
+    signals.push('no-taskbar');
+  }
+
+  // Mobile UA claiming devicePixelRatio === 1 (real mobile devices have DPR >= 2)
+  if (/Mobile|Android|iPhone/i.test(ua) && window.devicePixelRatio === 1) {
+    score += 15;
+    signals.push('mobile-ua-low-dpr');
+  }
+
+  return {
+    detector: 'navigator',
+    rawScore: Math.min(score, 100),
+    signals,
+  };
+}

package/src/detect/types.ts

@@ -0,0 +1,52 @@
+import type { ModelClassification } from '@toffee-at/shared';
+
+export type DetectorName =
+  | 'user-agent'
+  | 'headless'
+  | 'automation'
+  | 'behavioral'
+  | 'navigator'
+  | 'fingerprint';
+
+export interface DetectorResult {
+  detector: DetectorName;
+  rawScore: number; // 0-100
+  signals: string[];
+}
+
+export type RiskTier =
+  | 'definite-bot'    // probability >= 0.95
+  | 'likely-bot'      // probability >= 0.80
+  | 'suspicious'      // probability >= 0.50
+  | 'likely-human'    // probability >= 0.20
+  | 'definite-human'; // probability < 0.20
+
+export type AgentCategory =
+  | 'human'
+  | 'ai-assistant'
+  | 'ai-crawler'
+  | 'ai-agent'
+  | 'search-engine'
+  | 'social-preview'
+  | 'monitoring'
+  | 'scraper'
+  | 'automation-tool'
+  | 'unknown-bot';
+
+export interface DetectionOutput {
+  score: number;          // 0-100 legacy score
+  probability: number;    // 0.0-1.0
+  riskTier: RiskTier;
+  isAgent: boolean;
+  results: DetectorResult[];
+  signals: {
+    detector: string;
+    fired: boolean;
+    llr: number;
+    rawScore: number;
+    evidence: string[];
+  }[];
+
+  // ML model classification
+  classification: ModelClassification;
+}

package/src/detect/user-agent.ts

@@ -0,0 +1,21 @@
+import { KNOWN_AGENTS, matchAgent } from '@toffee-at/shared';
+import type { DetectorResult } from './types';
+
+export function detectUserAgent(): DetectorResult {
+  const ua = navigator.userAgent;
+  const match = matchAgent(ua);
+
+  if (match) {
+    return {
+      detector: 'user-agent',
+      rawScore: 100,
+      signals: [`matched-agent:${match.name}`],
+    };
+  }
+
+  return {
+    detector: 'user-agent',
+    rawScore: 0,
+    signals: [],
+  };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { createCore, type AgentRadarConfig } from './core';
+import type { DetectionOutput } from './detect/types';
+
+let instance: ReturnType<typeof createCore> | null = null;
+
+export function init(config: AgentRadarConfig) {
+  if (instance) return instance;
+  instance = createCore(config);
+  instance.start();
+  return instance;
+}
+
+export function identify(metadata: Record<string, string>) {
+  instance?.identify(metadata);
+}
+
+export function getDetection(): DetectionOutput | null {
+  return instance?.getDetection() ?? null;
+}
+
+export type { AgentRadarConfig } from './core';
+export type { DetectionOutput, RiskTier, AgentCategory } from './detect/types';

package/src/track/elements.ts

@@ -0,0 +1,105 @@
+import type { InteractionEvent, TrackingEvent } from './types';
+
+const TRACKED_SELECTOR = 'h1,h2,h3,h4,h5,h6,p,a,button,form,input,img,[data-ar-track]';
+
+function getSelector(el: Element): string {
+  if (el.id) return `#${el.id}`;
+  const arTrack = el.getAttribute('data-ar-track');
+  if (arTrack) return `[data-ar-track="${arTrack}"]`;
+  const tag = el.tagName.toLowerCase();
+  const cls = el.className && typeof el.className === 'string'
+    ? `.${el.className.trim().split(/\s+/).slice(0, 2).join('.')}`
+    : '';
+  return `${tag}${cls}`;
+}
+
+function getTextContent(el: Element): string | undefined {
+  const text = el.textContent?.trim().slice(0, 100);
+  return text || undefined;
+}
+
+export function setupElementTracking(onEvent: (event: TrackingEvent) => void): () => void {
+  const dwellMap = new Map<Element, number>();
+
+  // IntersectionObserver for visibility tracking
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          dwellMap.set(entry.target, Date.now());
+        } else {
+          const start = dwellMap.get(entry.target);
+          if (start) {
+            const event: InteractionEvent = {
+              type: 'interaction',
+              action: 'view',
+              selector: getSelector(entry.target),
+              tag: entry.target.tagName.toLowerCase(),
+              text: getTextContent(entry.target),
+              dwellMs: Date.now() - start,
+              url: location.href,
+              timestamp: Date.now(),
+            };
+            onEvent(event);
+            dwellMap.delete(entry.target);
+          }
+        }
+      }
+    },
+    { threshold: 0.5 }
+  );
+
+  // Observe existing elements
+  function observeElements() {
+    const elements = document.querySelectorAll(TRACKED_SELECTOR);
+    for (const el of elements) {
+      observer.observe(el);
+    }
+  }
+  observeElements();
+
+  // MutationObserver to pick up dynamically added elements
+  const mutationObserver = new MutationObserver(() => observeElements());
+  mutationObserver.observe(document.body, { childList: true, subtree: true });
+
+  // Event delegation for clicks
+  const onClick = (e: Event) => {
+    const target = (e.target as Element)?.closest?.(TRACKED_SELECTOR);
+    if (!target) return;
+    const event: InteractionEvent = {
+      type: 'interaction',
+      action: 'click',
+      selector: getSelector(target),
+      tag: target.tagName.toLowerCase(),
+      text: getTextContent(target),
+      url: location.href,
+      timestamp: Date.now(),
+    };
+    onEvent(event);
+  };
+
+  // Event delegation for input
+  const onInput = (e: Event) => {
+    const target = e.target as Element;
+    if (!target?.matches?.('input,textarea,select,[data-ar-track]')) return;
+    const event: InteractionEvent = {
+      type: 'interaction',
+      action: 'input',
+      selector: getSelector(target),
+      tag: target.tagName.toLowerCase(),
+      url: location.href,
+      timestamp: Date.now(),
+    };
+    onEvent(event);
+  };
+
+  document.body.addEventListener('click', onClick, { passive: true });
+  document.body.addEventListener('input', onInput, { passive: true });
+
+  return () => {
+    observer.disconnect();
+    mutationObserver.disconnect();
+    document.body.removeEventListener('click', onClick);
+    document.body.removeEventListener('input', onInput);
+  };
+}

package/src/track/index.ts

@@ -0,0 +1,15 @@
+import type { TrackingEvent } from './types';
+import { setupPageTracking } from './page';
+import { setupElementTracking } from './elements';
+
+export type { TrackingEvent, PageviewEvent, InteractionEvent } from './types';
+
+export function setupTracking(onEvent: (event: TrackingEvent) => void): () => void {
+  const destroyPage = setupPageTracking(onEvent);
+  const destroyElements = setupElementTracking(onEvent);
+
+  return () => {
+    destroyPage();
+    destroyElements();
+  };
+}

package/src/track/page.ts

@@ -0,0 +1,43 @@
+import type { PageviewEvent, TrackingEvent } from './types';
+
+export function setupPageTracking(onEvent: (event: TrackingEvent) => void): () => void {
+  let startTime = Date.now();
+
+  function emitPageview() {
+    const event: PageviewEvent = {
+      type: 'pageview',
+      url: location.href,
+      referrer: document.referrer,
+      timestamp: Date.now(),
+    };
+    startTime = Date.now();
+    onEvent(event);
+  }
+
+  // Emit initial pageview
+  emitPageview();
+
+  // Listen for popstate (back/forward navigation)
+  const onPopState = () => emitPageview();
+  window.addEventListener('popstate', onPopState);
+
+  // Monkey-patch pushState and replaceState for SPA navigation
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+
+  history.pushState = function (...args: Parameters<typeof history.pushState>) {
+    originalPushState(...args);
+    emitPageview();
+  };
+
+  history.replaceState = function (...args: Parameters<typeof history.replaceState>) {
+    originalReplaceState(...args);
+    emitPageview();
+  };
+
+  return () => {
+    window.removeEventListener('popstate', onPopState);
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+  };
+}

package/src/track/session.ts

@@ -0,0 +1,19 @@
+function fnv1a(str: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = (hash * 0x01000193) >>> 0;
+  }
+  return hash.toString(36);
+}
+
+export function createSessionId(): string {
+  const parts = [
+    navigator.userAgent,
+    `${screen.width}x${screen.height}`,
+    Intl.DateTimeFormat().resolvedOptions().timeZone,
+    navigator.language,
+    new Date().toDateString(), // daily rotation
+  ];
+  return fnv1a(parts.join('|'));
+}

package/src/track/types.ts

@@ -0,0 +1,19 @@
+export interface PageviewEvent {
+  type: 'pageview';
+  url: string;
+  referrer: string;
+  timestamp: number;
+}
+
+export interface InteractionEvent {
+  type: 'interaction';
+  action: 'click' | 'input' | 'view';
+  selector: string;
+  tag: string;
+  text?: string;
+  dwellMs?: number;
+  url: string;
+  timestamp: number;
+}
+
+export type TrackingEvent = PageviewEvent | InteractionEvent;