engagelab-captcha-sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,527 @@
+import { CaptchaConfig, VerifyResponse, ServiceError } from './types';
+import { collectFingerprint } from './fingerprint';
+import { detectHeadless } from './headless';
+import { collectTimingData } from './timing';
+import { TrajectoryRecorder } from './trajectory';
+import { computePoW } from './pow';
+import { checkIntegrity, setFunctionRefs } from './integrity';
+import { CaptchaAPI } from './api';
+import { CaptchaContainer } from './ui/container';
+import { injectStyles } from './ui/styles';
+import { InvisibleChallenge } from './challenges/invisible';
+import { setLocale, detectLocale, t, Locale } from './i18n';
+import { setTheme, CaptchaTheme } from './theme';
+import { initReporter, reportError, destroyReporter } from './reporter';
+import type { DeepProbeResult } from './deep_probes';
+import { PassiveSignalCollector } from './passive_signals';
+import { NativeMonitor } from './native_monitor';
+import { SessionPersist } from './session_persist';
+import { sdkLogger } from './logger';
+
+export type { DeepProbeResult };
+
+export { DegradationManager, DegradationConfig } from './degradation';
+
+export class EngageLabCaptcha {
+  private config: CaptchaConfig;
+  private api: CaptchaAPI;
+  private container = new CaptchaContainer();
+  private sessionId = '';
+  private sdkInitTime: number;
+  private pageTrajectory = new TrajectoryRecorder();
+  private passiveCollector = new PassiveSignalCollector();
+  private nativeMonitor = new NativeMonitor();
+  private sessionPersist = new SessionPersist();
+  private escalationDepth = 0;
+  private cachedCollectedData: { fingerprint: any; timingData: any; integrity: any; powResult: any } | null = null;
+  private static readonly MAX_ESCALATION_DEPTH = 5;
+
+  constructor(config: CaptchaConfig) {
+    this.config = {
+      mode: 'popup',
+      lang: 'zh-CN',
+      ...config,
+    };
+    if (this.config.debug) {
+      sdkLogger.enableDebug();
+    }
+    this.api = new CaptchaAPI(config.apiBase, config.siteKey);
+    sdkLogger.configure(config.apiBase, config.siteKey);
+    if (this.config.debug) {
+      sdkLogger.startAutoFlush(15000);
+    }
+    this.sdkInitTime = performance.now();
+
+    const locale = (this.config.lang as Locale) || detectLocale();
+    setLocale(locale);
+
+    if (this.config.theme) {
+      setTheme(this.config.theme as CaptchaTheme);
+    }
+
+    injectStyles();
+    setFunctionRefs(collectFingerprint, detectHeadless, computePoW);
+
+    initReporter(config.apiBase, config.siteKey);
+
+    this.pageTrajectory.start(document.body);
+    this.passiveCollector.start();
+    if (!this.config.disableEvalPatching) {
+      this.nativeMonitor.start();
+    }
+    this.sessionPersist.load().catch(() => {});
+    this.config.onReady?.();
+
+    sdkLogger.info(
+      'SDK',
+      `Initialized: siteKey=${config.siteKey?.substring(0, 8)}..., mode=${this.config.mode}, lang=${this.config.lang}`,
+    );
+  }
+
+  async execute(challengeType?: string): Promise<void> {
+    sdkLogger.info('SDK', `Execute called: challengeType=${challengeType || 'auto'}`);
+    try {
+      this.escalationDepth = 0;
+      this.cachedCollectedData = null;
+      const initResp = await this.api.init(this.config.siteKey, this.config.entityHash);
+      this.sessionId = initResp.sessionId;
+      sdkLogger.setSessionId(this.sessionId);
+
+      const type = challengeType || initResp.challengeType || 'invisible';
+      sdkLogger.info(
+        'SDK',
+        `Init response: sessionId=${this.sessionId?.substring(0, 8)}, type=${type}`,
+      );
+      await this.runChallenge(type, initResp);
+    } catch (err: any) {
+      sdkLogger.error('SDK', 'Execute failed', err?.message || err);
+      reportError(err instanceof Error ? err : new Error(err.message || 'Unknown error'));
+      if (err instanceof ServiceError) {
+        this.handleServiceUnavailable(err);
+      } else {
+        this.container.showResult(false, t('fail'));
+        this.config.onFail?.({ code: 'error', message: err.message || 'Unknown error' });
+      }
+    }
+  }
+
+  private async runChallenge(type: string, initResp: any): Promise<void> {
+    sdkLogger.info('SDK', `runChallenge enter: type=${type}`);
+    try {
+      switch (type) {
+        case 'invisible': return await this.runInvisible(initResp);
+        case 'slider': return await this.runSlider(initResp);
+        case 'spatial': return await this.runSpatial(initResp);
+        case 'rotate': return await this.runRotate(initResp);
+        case 'icons': return await this.runIcons(initResp);
+        case 'dragsort': return await this.runDragSort(initResp);
+        case 'grid': return await this.runGrid(initResp);
+        case 'physics': return await this.runPhysics(initResp);
+        default: return await this.runInvisible(initResp);
+      }
+    } finally {
+      sdkLogger.debug('SDK', `runChallenge exit: type=${type}`);
+    }
+  }
+
+  reset() {
+    sdkLogger.info('SDK', 'reset()');
+    this.container.close();
+    this.sessionId = '';
+  }
+
+  destroy() {
+    sdkLogger.info('SDK', 'destroy()');
+    this.passiveCollector.stop();
+    this.nativeMonitor.disable();
+    this.pageTrajectory.stop();
+    this.container.close();
+    destroyReporter();
+    sdkLogger.destroy();
+  }
+
+  private async collectAllData(initResp: any) {
+    if (this.cachedCollectedData && this.escalationDepth > 0) {
+      sdkLogger.debug('SDK', `collectAllData: reusing cached data for escalation depth=${this.escalationDepth}`);
+      return {
+        ...this.cachedCollectedData,
+        timingData: { ...this.cachedCollectedData.timingData, verificationComplete: performance.now() },
+      };
+    }
+
+    const start = performance.now();
+    const loadDeepProbes = import('./deep_probes').then(m => m.runDeepProbes());
+    const [fingerprint, headlessSignals, timingData, integrity, powResult, deepProbes] = await Promise.all([
+      collectFingerprint(this.config.fingerprint),
+      detectHeadless(),
+      Promise.resolve(collectTimingData(this.sdkInitTime)),
+      Promise.resolve(checkIntegrity()),
+      computePoW(initResp.powChallenge, initResp.powDifficulty),
+      loadDeepProbes,
+    ]);
+
+    fingerprint.headlessSignals = headlessSignals;
+    fingerprint.deep_probes = deepProbes;
+    fingerprint.passive_signals = this.passiveCollector.getResults();
+    fingerprint.native_traces = this.nativeMonitor.getTraces();
+    fingerprint.session_count = this.sessionPersist.getData().sessionCount;
+    timingData.verificationComplete = performance.now();
+
+    sdkLogger.debug('SDK', `collectAllData completed in ${(performance.now() - start).toFixed(1)}ms`, {
+      headlessSignals: headlessSignals.filter(s => s.detected).length,
+      deepProbes: deepProbes.filter(p => p.detected).length,
+    });
+
+    const result = { fingerprint, timingData, integrity, powResult };
+    this.cachedCollectedData = result;
+    return result;
+  }
+
+  private async runInvisible(initResp: any) {
+    this.container.showLoading();
+
+    const { fingerprint, timingData, integrity, powResult } = await this.collectAllData(initResp);
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'invisible',
+      fingerprint,
+      trajectory: this.pageTrajectory.getPoints().slice(-200),
+      powResult,
+      answer: { challengeType: 'invisible', passtime: performance.now() - this.sdkInitTime },
+      timing: timingData,
+      integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private async runSlider(initResp: any) {
+    const { fingerprint, timingData, integrity, powResult } = await this.collectAllData(initResp);
+
+    const targetX = initResp.challengeConfig?.targetX ?? Math.random() * 60 + 20;
+    const { SliderChallenge } = await import('./challenges/slider');
+    const slider = new SliderChallenge();
+    const { element, promise } = slider.create(targetX);
+    this.container.show(element, () => { slider.destroy(); this.config.onClose?.(); });
+
+    const sliderResult = await promise;
+    timingData.verificationComplete = performance.now();
+    this.container.showLoading();
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'slider',
+      fingerprint,
+      trajectory: sliderResult.trajectory,
+      powResult,
+      answer: { challengeType: 'slider', sliderX: sliderResult.sliderX, passtime: sliderResult.passtime },
+      timing: timingData,
+      integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private async runSpatial(initResp: any) {
+    this.container.showLoading();
+    const [challengeData, collected] = await Promise.all([
+      this.api.getChallenge(this.sessionId, 'spatial'),
+      this.collectAllData(initResp),
+    ]);
+
+    const { SpatialChallenge } = await import('./challenges/spatial');
+    const spatial = new SpatialChallenge();
+    const { element, promise } = spatial.create(
+      challengeData.imageBase64, challengeData.question, challengeData.options);
+    this.container.show(element, () => this.config.onClose?.());
+
+    const spatialResult = await promise;
+    collected.timingData.verificationComplete = performance.now();
+    this.container.showLoading();
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'spatial',
+      fingerprint: collected.fingerprint,
+      trajectory: this.pageTrajectory.getPoints().slice(-100),
+      powResult: collected.powResult,
+      answer: { challengeType: 'spatial', spatialAnswerIndex: spatialResult.answerIndex, passtime: spatialResult.passtime },
+      timing: collected.timingData,
+      integrity: collected.integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private async runRotate(initResp: any) {
+    this.container.showLoading();
+    const [challengeData, collected] = await Promise.all([
+      this.api.getChallenge(this.sessionId, 'rotate'),
+      this.collectAllData(initResp),
+    ]);
+
+    const { RotateChallenge } = await import('./challenges/rotate');
+    const rotate = new RotateChallenge();
+    const { element, promise } = rotate.create(challengeData.imageBase64);
+    this.container.show(element, () => this.config.onClose?.());
+
+    const rotateResult = await promise;
+    collected.timingData.verificationComplete = performance.now();
+    this.container.showLoading();
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'rotate',
+      fingerprint: collected.fingerprint,
+      trajectory: rotateResult.trajectory,
+      powResult: collected.powResult,
+      answer: { challengeType: 'rotate', rotateAngle: rotateResult.angle, passtime: rotateResult.passtime },
+      timing: collected.timingData,
+      integrity: collected.integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private async runIcons(initResp: any) {
+    this.container.showLoading();
+    const [challengeData, collected] = await Promise.all([
+      this.api.getChallenge(this.sessionId, 'icons'),
+      this.collectAllData(initResp),
+    ]);
+
+    const { IconChallenge } = await import('./challenges/icons');
+    const icons = new IconChallenge();
+    const { element, promise } = icons.create(
+      challengeData.imageBase64, challengeData.instruction, challengeData.iconCount || 9);
+    this.container.show(element, () => this.config.onClose?.());
+
+    const iconResult = await promise;
+    collected.timingData.verificationComplete = performance.now();
+    this.container.showLoading();
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'icons',
+      fingerprint: collected.fingerprint,
+      trajectory: this.pageTrajectory.getPoints().slice(-100),
+      powResult: collected.powResult,
+      answer: { challengeType: 'icons', iconClicks: iconResult.clicks, passtime: iconResult.passtime },
+      timing: collected.timingData,
+      integrity: collected.integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private async runDragSort(initResp: any) {
+    this.container.showLoading();
+    const [challengeData, collected] = await Promise.all([
+      this.api.getChallenge(this.sessionId, 'dragsort'),
+      this.collectAllData(initResp),
+    ]);
+
+    const { DragSortChallenge } = await import('./challenges/dragsort');
+    const challenge = new DragSortChallenge();
+    const { element, getResult } = challenge.create(
+      challengeData.imageBase64, challengeData.instruction, challengeData.itemCount || 4);
+
+    const submitWrapper = document.createElement('div');
+    submitWrapper.style.cssText = 'width:100%;max-width:380px;margin:12px auto 0;display:flex;gap:8px;justify-content:center;';
+
+    const confirmBtn = document.createElement('button');
+    confirmBtn.textContent = t('dragsort.confirm');
+    confirmBtn.style.cssText = 'padding:8px 24px;background:#1890ff;color:white;border:none;border-radius:6px;cursor:pointer;font-size:14px;';
+    submitWrapper.appendChild(confirmBtn);
+
+    const container = document.createElement('div');
+    container.appendChild(element);
+    container.appendChild(submitWrapper);
+    this.container.show(container, () => { challenge.destroy(); this.config.onClose?.(); });
+
+    const dragResult = await new Promise<any>((resolve) => {
+      confirmBtn.addEventListener('click', () => resolve(getResult()));
+    });
+
+    collected.timingData.verificationComplete = performance.now();
+    this.container.showLoading();
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'dragsort',
+      fingerprint: collected.fingerprint,
+      trajectory: dragResult.trajectory,
+      powResult: collected.powResult,
+      answer: {
+        challengeType: 'dragsort',
+        dragSortOrder: dragResult.sortOrder,
+        dragEvents: dragResult.dragEvents,
+        passtime: dragResult.passtime,
+      },
+      timing: collected.timingData,
+      integrity: collected.integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private async runGrid(initResp: any) {
+    this.container.showLoading();
+    const [challengeData, collected] = await Promise.all([
+      this.api.getChallenge(this.sessionId, 'grid'),
+      this.collectAllData(initResp),
+    ]);
+
+    const { GridChallenge } = await import('./challenges/grid');
+    const challenge = new GridChallenge();
+    const { element, getResult } = challenge.create(
+      challengeData.imageBase64, challengeData.instruction, challengeData.gridSize || 3);
+
+    const submitWrapper = document.createElement('div');
+    submitWrapper.style.cssText = 'width:100%;max-width:380px;margin:12px auto 0;display:flex;gap:8px;justify-content:center;';
+
+    const confirmBtn = document.createElement('button');
+    confirmBtn.textContent = t('grid.confirm');
+    confirmBtn.style.cssText = 'padding:8px 24px;background:#1890ff;color:white;border:none;border-radius:6px;cursor:pointer;font-size:14px;';
+    submitWrapper.appendChild(confirmBtn);
+
+    const outerContainer = document.createElement('div');
+    outerContainer.appendChild(element);
+    outerContainer.appendChild(submitWrapper);
+    this.container.show(outerContainer, () => { challenge.destroy(); this.config.onClose?.(); });
+
+    const gridResult = await new Promise<any>((resolve) => {
+      confirmBtn.addEventListener('click', () => resolve(getResult()));
+    });
+
+    collected.timingData.verificationComplete = performance.now();
+    this.container.showLoading();
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'grid',
+      fingerprint: collected.fingerprint,
+      trajectory: this.pageTrajectory.getPoints().slice(-100),
+      powResult: collected.powResult,
+      answer: {
+        challengeType: 'grid',
+        gridSelectedCells: gridResult.selectedCells,
+        passtime: gridResult.passtime,
+      },
+      timing: collected.timingData,
+      integrity: collected.integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private async runPhysics(initResp: any) {
+    this.container.showLoading();
+    const [challengeData, collected] = await Promise.all([
+      this.api.getChallenge(this.sessionId, 'physics'),
+      this.collectAllData(initResp),
+    ]);
+
+    const { PhysicsChallenge } = await import('./challenges/physics');
+    const challenge = new PhysicsChallenge();
+
+    let physicsConfig = challengeData.challengeConfig || challengeData;
+    if (typeof challengeData.configJson === 'string') {
+      try {
+        physicsConfig = { ...JSON.parse(challengeData.configJson), variant: challengeData.variant };
+      } catch { /* use fallback */ }
+    }
+    const previewImg = challengeData.previewBase64 || challengeData.previewImage || '';
+
+    const { element, promise } = challenge.create(physicsConfig, previewImg);
+    this.container.show(element, () => { challenge.destroy(); this.config.onClose?.(); });
+
+    const physicsResult = await promise;
+    collected.timingData.verificationComplete = performance.now();
+    this.container.showLoading();
+
+    const result = await this.api.verify(this.sessionId, {
+      challengeType: 'physics',
+      fingerprint: collected.fingerprint,
+      trajectory: this.pageTrajectory.getPoints().slice(-100),
+      powResult: collected.powResult,
+      answer: {
+        challengeType: 'physics',
+        physicsAnswer: physicsResult.answer,
+        interactionEvents: physicsResult.interactionEvents,
+        passtime: physicsResult.passtime,
+      },
+      timing: collected.timingData,
+      integrity: collected.integrity,
+      entityHash: this.config.entityHash,
+    });
+
+    this.handleResult(result, initResp);
+  }
+
+  private handleResult(result: VerifyResponse, initResp: any) {
+    sdkLogger.info(
+      'SDK',
+      `Verify result: success=${result.success}, decision=${result.decision}, score=${result.score}, degraded=${result.degraded}, nextChallenge=${result.nextChallenge}`,
+    );
+
+    if (result.decision === 'service_unavailable' || (result.degraded && !result.success)) {
+      sdkLogger.warn('SDK', 'handleResult: service unavailable — notifying developer');
+      this.handleServiceUnavailable(
+        new ServiceError('service_unavailable', 'Risk engine is temporarily unavailable'),
+      );
+      return;
+    }
+
+    if (result.success || result.decision === 'pass') {
+      sdkLogger.info('SDK', 'handleResult: pass — showing success');
+      this.container.showResult(true, t('success'));
+      this.sessionPersist.recordVerify(this.sessionId).catch(() => {});
+      this.config.onSuccess?.(result.validateToken, result.riskLabels || []);
+    } else if (result.nextChallenge) {
+      this.escalationDepth++;
+      if (this.escalationDepth > EngageLabCaptcha.MAX_ESCALATION_DEPTH) {
+        sdkLogger.warn('SDK', `handleResult: escalation depth exceeded (${this.escalationDepth}), giving up`);
+        this.container.showResult(false, t('fail'));
+        this.config.onFail?.({ code: 'escalation_limit', message: 'Too many challenge attempts' });
+        return;
+      }
+      sdkLogger.info('SDK', `handleResult: challenge — next=${result.nextChallenge} (depth=${this.escalationDepth})`);
+      this.container.close();
+      this.runChallenge(result.nextChallenge, initResp).catch((err) => {
+        sdkLogger.error('SDK', `Challenge escalation failed: ${err}`);
+        if (err instanceof ServiceError) {
+          this.handleServiceUnavailable(err);
+        } else {
+          this.container.showResult(false, t('fail'));
+          this.config.onFail?.({ code: 'challenge_error', message: String(err) });
+        }
+      });
+    } else {
+      sdkLogger.warn('SDK', 'handleResult: deny');
+      this.container.showResult(false, t('fail'));
+      this.config.onFail?.({ code: 'denied', message: `Risk score: ${result.score}` });
+    }
+  }
+
+  private handleServiceUnavailable(err: ServiceError) {
+    this.container.close();
+    const error = { code: err.code, message: err.message };
+    if (this.config.onError) {
+      sdkLogger.info('SDK', 'Service unavailable — calling onError callback');
+      this.config.onError(error);
+    } else {
+      sdkLogger.info('SDK', 'Service unavailable — no onError callback, falling back to onFail');
+      this.config.onFail?.(error);
+    }
+  }
+}
+
+export { registerWebComponent, EngageLabCaptchaElement } from './web-component';
+
+if (typeof window !== 'undefined') {
+  (window as any).EngageLabCaptcha = EngageLabCaptcha;
+}
+
+export default EngageLabCaptcha;

package/src/integrity.ts

@@ -0,0 +1,100 @@
+import { IntegrityData } from './types';
+import { sdkLogger } from './logger';
+
+export function checkIntegrity(): IntegrityData {
+  const patchedFunctions: string[] = [];
+
+  const fnChecks = [
+    { name: 'fetch', fn: window.fetch },
+    { name: 'XMLHttpRequest.send', fn: XMLHttpRequest.prototype.send },
+    { name: 'XMLHttpRequest.open', fn: XMLHttpRequest.prototype.open },
+    { name: 'canvas.toDataURL', fn: HTMLCanvasElement.prototype.toDataURL },
+    { name: 'canvas.getContext', fn: HTMLCanvasElement.prototype.getContext },
+    { name: 'Date.now', fn: Date.now },
+    { name: 'performance.now', fn: performance.now },
+    { name: 'Math.random', fn: Math.random },
+  ];
+
+  for (const { name, fn } of fnChecks) {
+    if (fn) {
+      try {
+        const str = Function.prototype.toString.call(fn);
+        if (!str.includes('[native code]') && !str.includes('{ [native code] }')) {
+          patchedFunctions.push(name);
+        }
+      } catch {
+        patchedFunctions.push(name + '_error');
+      }
+    }
+  }
+
+  const devtoolsDetected = detectDevTools();
+
+  let sdkHash = '';
+  try {
+    const criticalCode = [
+      collectFingerprint_ref.toString().length,
+      detectHeadless_ref.toString().length,
+      computePoW_ref.toString().length,
+    ].join(':');
+    sdkHash = simpleHash(criticalCode);
+  } catch {
+    sdkHash = 'unknown';
+  }
+
+  const out: IntegrityData = { sdkHash, patchedFunctions, devtoolsDetected };
+  sdkLogger.info('Integrity', 'Check complete', {
+    sdkHash,
+    patchedCount: patchedFunctions.length,
+    patchedFunctions,
+    devtoolsDetected,
+  });
+  return out;
+}
+
+function detectDevTools(): boolean {
+  let detected = false;
+
+  // Method 1: debugger timing
+  const t1 = performance.now();
+  // Method 2: console object check
+  const element = new Image();
+  Object.defineProperty(element, 'id', {
+    get: function () { detected = true; return ''; }
+  });
+
+  try {
+    // Only logs when devtools is open
+    console.debug(element);
+  } catch {}
+
+  // Method 3: window size discrepancy (F12 docked)
+  const widthThreshold = window.outerWidth - window.innerWidth > 160;
+  const heightThreshold = window.outerHeight - window.innerHeight > 160;
+  if (widthThreshold || heightThreshold) {
+    detected = true;
+  }
+
+  return detected;
+}
+
+function simpleHash(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(16);
+}
+
+// References to critical functions for SDK hash computation.
+// These will be set by the main module during initialization.
+let collectFingerprint_ref: Function = () => {};
+let detectHeadless_ref: Function = () => {};
+let computePoW_ref: Function = () => {};
+
+export function setFunctionRefs(fp: Function, hl: Function, pow: Function) {
+  collectFingerprint_ref = fp;
+  detectHeadless_ref = hl;
+  computePoW_ref = pow;
+}