engagelab-captcha-sdk 1.0.0

package/src/reporter.ts

@@ -0,0 +1,75 @@
+/**
+ * Error reporting and performance monitoring for the SDK.
+ * Collects exceptions and performance metrics, sends via beacon.
+ */
+
+interface ErrorReport {
+  type: 'error' | 'perf';
+  timestamp: number;
+  message: string;
+  stack?: string;
+  context?: Record<string, string | number>;
+}
+
+let reportEndpoint = '';
+let siteKey = '';
+const buffer: ErrorReport[] = [];
+const MAX_BUFFER = 20;
+const FLUSH_INTERVAL = 30000;
+let flushTimer: ReturnType<typeof setInterval> | null = null;
+
+export function initReporter(endpoint: string, key: string): void {
+  reportEndpoint = endpoint;
+  siteKey = key;
+  if (!flushTimer) {
+    flushTimer = setInterval(flush, FLUSH_INTERVAL);
+  }
+}
+
+export function reportError(error: Error, context?: Record<string, string | number>): void {
+  buffer.push({
+    type: 'error',
+    timestamp: Date.now(),
+    message: error.message,
+    stack: error.stack?.substring(0, 500),
+    context,
+  });
+  if (buffer.length >= MAX_BUFFER) flush();
+}
+
+export function reportPerf(metric: string, durationMs: number): void {
+  buffer.push({
+    type: 'perf',
+    timestamp: Date.now(),
+    message: metric,
+    context: { durationMs },
+  });
+}
+
+function flush(): void {
+  if (!reportEndpoint || buffer.length === 0) return;
+
+  const payload = JSON.stringify({
+    siteKey,
+    reports: buffer.splice(0, MAX_BUFFER),
+  });
+
+  if (navigator.sendBeacon) {
+    navigator.sendBeacon(reportEndpoint + '/v1/sdk/report', payload);
+  } else {
+    fetch(reportEndpoint + '/v1/sdk/report', {
+      method: 'POST',
+      body: payload,
+      headers: { 'Content-Type': 'application/json' },
+      keepalive: true,
+    }).catch(() => {});
+  }
+}
+
+export function destroyReporter(): void {
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = null;
+  }
+  flush();
+}

package/src/session_persist.ts

@@ -0,0 +1,90 @@
+/**
+ * SDK Session Persistence — store session metadata in IndexedDB for cross-page context.
+ *
+ * Persists: sessionCount, lastVerifyTime, fingerprintCache hash.
+ * Used to report returning-user signals to the risk engine.
+ */
+
+const DB_NAME = 'engagelab_captcha';
+const STORE_NAME = 'session';
+const DB_VERSION = 1;
+
+export interface SessionData {
+  sessionCount: number;
+  lastVerifyTime: number;
+  fingerprintHash: string;
+}
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (typeof indexedDB === 'undefined') {
+      reject(new Error('IndexedDB not available'));
+      return;
+    }
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+
+function getItem(db: IDBDatabase, key: string): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readonly');
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.get(key);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function setItem(db: IDBDatabase, key: string, value: any): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readwrite');
+    const store = tx.objectStore(STORE_NAME);
+    const req = store.put(value, key);
+    req.onsuccess = () => resolve();
+    req.onerror = () => reject(req.error);
+  });
+}
+
+export class SessionPersist {
+  private db: IDBDatabase | null = null;
+  private data: SessionData = { sessionCount: 0, lastVerifyTime: 0, fingerprintHash: '' };
+
+  async load(): Promise<SessionData> {
+    try {
+      this.db = await openDb();
+      const stored = await getItem(this.db, 'session_data');
+      if (stored) {
+        this.data = { ...this.data, ...stored };
+      }
+      this.data.sessionCount++;
+      await setItem(this.db, 'session_data', this.data);
+    } catch {
+      // Silently degrade — persistence is not critical
+    }
+    return this.data;
+  }
+
+  async recordVerify(fingerprintHash: string): Promise<void> {
+    this.data.lastVerifyTime = Date.now();
+    this.data.fingerprintHash = fingerprintHash;
+    try {
+      if (this.db) {
+        await setItem(this.db, 'session_data', this.data);
+      }
+    } catch {
+      // Silently degrade
+    }
+  }
+
+  getData(): SessionData {
+    return { ...this.data };
+  }
+}

package/src/theme.ts

@@ -0,0 +1,41 @@
+export interface CaptchaTheme {
+  primaryColor?: string;
+  successColor?: string;
+  errorColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  borderRadius?: number;
+  fontFamily?: string;
+}
+
+const DEFAULT_THEME: Required<CaptchaTheme> = {
+  primaryColor: '#1890ff',
+  successColor: '#52c41a',
+  errorColor: '#ff4d4f',
+  backgroundColor: '#ffffff',
+  textColor: '#333333',
+  borderRadius: 8,
+  fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+};
+
+let activeTheme: Required<CaptchaTheme> = { ...DEFAULT_THEME };
+
+export function setTheme(theme: CaptchaTheme): void {
+  activeTheme = { ...DEFAULT_THEME, ...theme };
+  applyThemeToDOM();
+}
+
+export function getTheme(): Required<CaptchaTheme> {
+  return activeTheme;
+}
+
+function applyThemeToDOM(): void {
+  const root = document.documentElement;
+  root.style.setProperty('--captcha-primary', activeTheme.primaryColor);
+  root.style.setProperty('--captcha-success', activeTheme.successColor);
+  root.style.setProperty('--captcha-error', activeTheme.errorColor);
+  root.style.setProperty('--captcha-bg', activeTheme.backgroundColor);
+  root.style.setProperty('--captcha-text', activeTheme.textColor);
+  root.style.setProperty('--captcha-radius', activeTheme.borderRadius + 'px');
+  root.style.setProperty('--captcha-font', activeTheme.fontFamily);
+}

package/src/timing.ts

@@ -0,0 +1,79 @@
+import { TimingData } from './types';
+import { sdkLogger } from './logger';
+
+export function collectTimingData(sdkInitTime: number): TimingData {
+  const measurements = runJSBenchmarks();
+
+  let precision = 0;
+  const times: number[] = [];
+  for (let i = 0; i < 20; i++) {
+    const t1 = performance.now();
+    const t2 = performance.now();
+    if (t2 > t1) times.push(t2 - t1);
+  }
+  if (times.length > 0) {
+    precision = times.reduce((a, b) => a + b, 0) / times.length;
+  }
+
+  const data: TimingData = {
+    domContentLoaded: performance.timing?.domContentLoadedEventEnd || 0,
+    sdkInitTime,
+    interactionStart: 0,
+    verificationComplete: 0,
+    jsMeasurements: measurements,
+    performanceNowPrecision: precision,
+  };
+  sdkLogger.debug('Timing', 'Collected', {
+    domContentLoaded: data.domContentLoaded,
+    performanceNowPrecision: precision,
+    benchmarks: measurements.map(m => `${m.operation}=${m.durationMs.toFixed(2)}ms`),
+  });
+  return data;
+}
+
+function runJSBenchmarks(): { operation: string; durationMs: number }[] {
+  const results: { operation: string; durationMs: number }[] = [];
+
+  // DOM operation benchmark
+  const t1 = performance.now();
+  const div = document.createElement('div');
+  for (let i = 0; i < 100; i++) {
+    div.setAttribute('data-test', String(i));
+    div.innerHTML = `<span>${i}</span>`;
+  }
+  results.push({ operation: 'dom_operation', durationMs: performance.now() - t1 });
+
+  // Canvas draw benchmark
+  const t2 = performance.now();
+  const canvas = document.createElement('canvas');
+  canvas.width = 100;
+  canvas.height = 100;
+  const ctx = canvas.getContext('2d');
+  if (ctx) {
+    for (let i = 0; i < 50; i++) {
+      ctx.fillStyle = `rgb(${i * 5},${i * 3},${i * 4})`;
+      ctx.fillRect(i, i, 50, 50);
+      ctx.arc(50, 50, 30, 0, Math.PI * 2);
+      ctx.stroke();
+    }
+  }
+  results.push({ operation: 'canvas_draw', durationMs: performance.now() - t2 });
+
+  // Regex benchmark
+  const t3 = performance.now();
+  const text = 'Lorem ipsum dolor sit amet '.repeat(100);
+  for (let i = 0; i < 50; i++) {
+    /\b\w{5,}\b/g.exec(text);
+  }
+  results.push({ operation: 'regex_match', durationMs: performance.now() - t3 });
+
+  // JSON benchmark
+  const t4 = performance.now();
+  const obj = { a: Array.from({ length: 1000 }, (_, i) => ({ id: i, value: `item_${i}` })) };
+  for (let i = 0; i < 10; i++) {
+    JSON.parse(JSON.stringify(obj));
+  }
+  results.push({ operation: 'json_serialize', durationMs: performance.now() - t4 });
+
+  return results;
+}

package/src/trajectory.ts

@@ -0,0 +1,110 @@
+import { TrajectoryPoint } from './types';
+import { sdkLogger } from './logger';
+
+export class TrajectoryRecorder {
+  private points: TrajectoryPoint[] = [];
+  private recording = false;
+  private element: HTMLElement | null = null;
+  private handlers: { type: string; fn: EventListener }[] = [];
+
+  start(element: HTMLElement) {
+    this.points = [];
+    this.recording = true;
+    this.element = element;
+    this.bindEvents();
+    sdkLogger.info('Trajectory', 'Recording start', { tag: element.tagName });
+  }
+
+  stop(): TrajectoryPoint[] {
+    this.recording = false;
+    this.unbindEvents();
+    sdkLogger.info('Trajectory', 'Recording stop', { pointCount: this.points.length });
+    return [...this.points];
+  }
+
+  getPoints(): TrajectoryPoint[] {
+    return [...this.points];
+  }
+
+  private bindEvents() {
+    const el = this.element || document;
+
+    const mouseMove = (e: Event) => this.onMouseMove(e as MouseEvent);
+    const mouseDown = (e: Event) => this.onMouseDown(e as MouseEvent);
+    const mouseUp = (e: Event) => this.onMouseUp(e as MouseEvent);
+    const touchStart = (e: Event) => this.onTouchEvent(e as TouchEvent, 'touchstart');
+    const touchMove = (e: Event) => this.onTouchEvent(e as TouchEvent, 'touchmove');
+    const touchEnd = (e: Event) => this.onTouchEvent(e as TouchEvent, 'touchend');
+    const click = (e: Event) => this.onClick(e as MouseEvent);
+
+    el.addEventListener('mousemove', mouseMove, { passive: true });
+    el.addEventListener('mousedown', mouseDown, { passive: true });
+    el.addEventListener('mouseup', mouseUp, { passive: true });
+    el.addEventListener('touchstart', touchStart, { passive: true });
+    el.addEventListener('touchmove', touchMove, { passive: true });
+    el.addEventListener('touchend', touchEnd, { passive: true });
+    el.addEventListener('click', click, { passive: true });
+
+    this.handlers = [
+      { type: 'mousemove', fn: mouseMove },
+      { type: 'mousedown', fn: mouseDown },
+      { type: 'mouseup', fn: mouseUp },
+      { type: 'touchstart', fn: touchStart },
+      { type: 'touchmove', fn: touchMove },
+      { type: 'touchend', fn: touchEnd },
+      { type: 'click', fn: click },
+    ];
+  }
+
+  private unbindEvents() {
+    const el = this.element || document;
+    for (const h of this.handlers) {
+      el.removeEventListener(h.type, h.fn);
+    }
+    this.handlers = [];
+  }
+
+  private addPoint(x: number, y: number, eventType: string, isTrusted: boolean,
+    movementX = 0, movementY = 0, buttons = 0, force?: number, radiusX?: number, radiusY?: number) {
+    if (!this.recording) return;
+    this.points.push({
+      x: Math.round(x * 100) / 100,
+      y: Math.round(y * 100) / 100,
+      timestamp: performance.now(),
+      eventType,
+      isTrusted,
+      movementX,
+      movementY,
+      buttons,
+      force,
+      radiusX,
+      radiusY,
+    });
+  }
+
+  private onMouseMove(e: MouseEvent) {
+    this.addPoint(e.clientX, e.clientY, 'mousemove', e.isTrusted, e.movementX, e.movementY, e.buttons);
+  }
+
+  private onMouseDown(e: MouseEvent) {
+    this.addPoint(e.clientX, e.clientY, 'mousedown', e.isTrusted, 0, 0, e.buttons);
+  }
+
+  private onMouseUp(e: MouseEvent) {
+    this.addPoint(e.clientX, e.clientY, 'mouseup', e.isTrusted, 0, 0, e.buttons);
+  }
+
+  private onClick(e: MouseEvent) {
+    this.addPoint(e.clientX, e.clientY, 'click', e.isTrusted);
+  }
+
+  private onTouchEvent(e: TouchEvent, eventType: string) {
+    const touch = e.touches[0] || e.changedTouches[0];
+    if (touch) {
+      this.addPoint(
+        touch.clientX, touch.clientY, eventType, e.isTrusted,
+        0, 0, 0, (touch as any).force, (touch as any).radiusX, (touch as any).radiusY,
+      );
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,199 @@
+import type { DeepProbeResult } from './deep_probes';
+import type { PassiveSignalResult } from './passive_signals';
+
+export interface CaptchaConfig {
+  siteKey: string;
+  apiBase: string;
+  /** When true, enables verbose SDK logging (same effect as localStorage engagelab_captcha_debug). */
+  debug?: boolean;
+  mode?: 'popup' | 'inline' | 'invisible';
+  lang?: string;
+  entityHash?: string;
+  theme?: ThemeConfig;
+  fingerprint?: FingerprintOptions;
+  /** Disable eval/Function.constructor wrapping (e.g. to avoid HMR conflicts). Default: false */
+  disableEvalPatching?: boolean;
+  onReady?: () => void;
+  onSuccess?: (token: string, riskLabels: string[]) => void;
+  onFail?: (error: CaptchaError) => void;
+  /**
+   * Called when the CAPTCHA service is unavailable (risk engine down, HTTP 503, etc.).
+   * The developer should implement their own degradation strategy here.
+   * If not provided, falls back to onFail with code="service_unavailable".
+   *
+   * Recommended actions:
+   * - Allow the user through for low-risk business scenarios
+   * - Block the user for high-risk scenarios (e.g. payment)
+   * - Switch to an alternative verification method (e.g. SMS verification)
+   */
+  onError?: (error: CaptchaError) => void;
+  onClose?: () => void;
+}
+
+export interface FingerprintOptions {
+  /** Audio fingerprint via OfflineAudioContext (no mic, no permission needed). Default: true */
+  audio?: boolean;
+  /** Canvas fingerprint. Default: true */
+  canvas?: boolean;
+  /** WebGL renderer/vendor fingerprint. Default: true */
+  webgl?: boolean;
+  /** Font detection via DOM measurement. Default: true */
+  fonts?: boolean;
+  /** WebRTC local IP detection. Default: true */
+  webrtc?: boolean;
+}
+
+export interface ThemeConfig {
+  primaryColor?: string;
+  successColor?: string;
+  errorColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  borderRadius?: number;
+  fontFamily?: string;
+  darkMode?: boolean;
+}
+
+export interface CaptchaError {
+  code: string;
+  message: string;
+}
+
+/**
+ * Thrown when the CAPTCHA backend service is unavailable (HTTP 503 or
+ * verify returns decision="service_unavailable"). The developer should
+ * implement their own degradation strategy in the onError callback.
+ */
+export class ServiceError extends Error {
+  public readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'ServiceError';
+    this.code = code;
+  }
+}
+
+export interface Fingerprint {
+  canvasHash: string;
+  webglRenderer: string;
+  webglVendor: string;
+  webglHash: string;
+  audioHash: string;
+  screenWidth: number;
+  screenHeight: number;
+  colorDepth: number;
+  devicePixelRatio: number;
+  timezone: string;
+  timezoneOffset: number;
+  language: string;
+  languages: string[];
+  platform: string;
+  hardwareConcurrency: number;
+  deviceMemory: number;
+  maxTouchPoints: number;
+  fonts: string[];
+  pluginCount: number;
+  webdriver: boolean;
+  hasChromeRuntime: boolean;
+  connectionType: string;
+  screenAvailWidth: number;
+  screenAvailHeight: number;
+  outerWidth: number;
+  outerHeight: number;
+  innerWidth: number;
+  innerHeight: number;
+  headlessSignals: HeadlessSignal[];
+  mathFp: MathFingerprint;
+  storageInfo: StorageInfo;
+  /** Deep environment probes (snake_case key matches server env analyzer). */
+  deep_probes?: DeepProbeResult[];
+  /** Background behavioral signals collected before challenge interaction. */
+  passive_signals?: PassiveSignalResult;
+  /** Stack trace records from wrapped native functions. */
+  native_traces?: NativeTrace[];
+  /** Number of SDK sessions from this browser (persisted via IndexedDB). */
+  session_count?: number;
+}
+
+export interface NativeTrace {
+  fn: string;
+  stack: string;
+  timestamp: number;
+}
+
+export interface HeadlessSignal {
+  name: string;
+  detected: boolean;
+  value: string;
+  weight: number;
+}
+
+export interface MathFingerprint {
+  tanValue: number;
+  atan2Value: number;
+  logValue: number;
+  sinValue: number;
+}
+
+export interface StorageInfo {
+  localStorage: boolean;
+  sessionStorage: boolean;
+  indexedDb: boolean;
+}
+
+export interface TrajectoryPoint {
+  x: number;
+  y: number;
+  timestamp: number;
+  eventType: string;
+  isTrusted: boolean;
+  movementX: number;
+  movementY: number;
+  buttons: number;
+  force?: number;
+  radiusX?: number;
+  radiusY?: number;
+}
+
+export interface PowResult {
+  challenge: string;
+  nonce: string;
+  difficulty: number;
+  computationTimeMs: number;
+  iterations: number;
+}
+
+export interface TimingData {
+  domContentLoaded: number;
+  sdkInitTime: number;
+  interactionStart: number;
+  verificationComplete: number;
+  jsMeasurements: { operation: string; durationMs: number }[];
+  performanceNowPrecision: number;
+}
+
+export interface IntegrityData {
+  sdkHash: string;
+  patchedFunctions: string[];
+  devtoolsDetected: boolean;
+}
+
+export interface InitResponse {
+  sessionId: string;
+  challengeType: string;
+  powDifficulty: number;
+  powChallenge: string;
+  challengeConfig: any;
+  publicKey: string;
+}
+
+export interface VerifyResponse {
+  success: boolean;
+  decision: string;
+  score: number;
+  riskLabels: string[];
+  validateToken: string;
+  layerResults?: any[];
+  nextChallenge?: string;
+  degraded?: boolean;
+}