engagelab-captcha-sdk 1.0.0

package/dist/types/api.d.ts

@@ -0,0 +1,12 @@
+import { InitResponse, VerifyResponse } from './types';
+export declare class CaptchaAPI {
+    private baseUrl;
+    private siteKey;
+    constructor(baseUrl: string, siteKey?: string);
+    init(siteKey: string, entityHash?: string): Promise<InitResponse>;
+    verify(sessionId: string, data: any): Promise<VerifyResponse>;
+    getChallenge(sessionId: string, type: string): Promise<any>;
+    getResult(sessionId: string): Promise<any>;
+    private post;
+    private get;
+}

package/dist/types/challenges/dragsort.d.ts

@@ -0,0 +1,24 @@
+export interface DragSortResult {
+    sortOrder: number[];
+    trajectory: any[];
+    passtime: number;
+    dragEvents: {
+        fromIndex: number;
+        toIndex: number;
+        timestamp: number;
+    }[];
+}
+export declare class DragSortChallenge {
+    private recorder;
+    private startTime;
+    private currentOrder;
+    private dragEvents;
+    private draggedEl;
+    create(imageBase64: string, instruction: string, itemCount: number): {
+        element: HTMLElement;
+        getResult: () => DragSortResult;
+    };
+    private getCurrentOrder;
+    private setupDragHandlers;
+    destroy(): void;
+}

package/dist/types/challenges/grid.d.ts

@@ -0,0 +1,20 @@
+export interface GridResult {
+    selectedCells: number[];
+    clickSequence: {
+        cell: number;
+        timestamp: number;
+    }[];
+    passtime: number;
+}
+export declare class GridChallenge {
+    private startTime;
+    private selected;
+    private clickSequence;
+    private cellElements;
+    create(imageBase64: string, instruction: string, gridSize: number): {
+        element: HTMLElement;
+        getResult: () => GridResult;
+    };
+    private toggleCell;
+    destroy(): void;
+}

package/dist/types/challenges/icons.d.ts

@@ -0,0 +1,18 @@
+export interface IconResult {
+    clicks: {
+        x: number;
+        y: number;
+        timestamp: number;
+        index: number;
+    }[];
+    passtime: number;
+}
+export declare class IconChallenge {
+    private resolve?;
+    private clicks;
+    private startTime;
+    create(imageBase64: string, instruction: string, iconCount: number): {
+        element: HTMLElement;
+        promise: Promise<IconResult>;
+    };
+}

package/dist/types/challenges/invisible.d.ts

@@ -0,0 +1,8 @@
+export declare class InvisibleChallenge {
+    private element;
+    private verified;
+    createTrigger(onClick: () => void): HTMLElement;
+    showLoading(): void;
+    showSuccess(): void;
+    showFail(): void;
+}

package/dist/types/challenges/physics.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Physics-based interactive CAPTCHA challenge.
+ *
+ * Renders 2D physics simulations using Canvas:
+ * - Tilt Ball: tilt a platform to guide a ball into a target hole
+ * - Gravity Drop: predict where an object lands
+ * - Balance Scale: place weights to balance a scale
+ *
+ * These challenges are extremely difficult for AI/ML because they require
+ * real-time spatial-physical reasoning, not just image recognition.
+ */
+interface PhysicsResult {
+    answer: Record<string, any> | string;
+    passtime: number;
+    interactionEvents?: Array<{
+        type: string;
+        time: number;
+        value: any;
+    }>;
+    events?: any[];
+    error?: string;
+}
+export declare class PhysicsChallenge {
+    private canvas;
+    private ctx;
+    private startTime;
+    private events;
+    private animFrameId;
+    private boundListeners;
+    create(challengeConfig: any, previewBase64: string): {
+        element: HTMLElement;
+        promise: Promise<PhysicsResult>;
+    };
+    destroy(): void;
+    private addListener;
+    private setupTiltBall;
+    private setupGravityDrop;
+    private setupBalanceScale;
+}
+export {};

package/dist/types/challenges/rotate.d.ts

@@ -0,0 +1,14 @@
+export interface RotateResult {
+    angle: number;
+    trajectory: any[];
+    passtime: number;
+}
+export declare class RotateChallenge {
+    private recorder;
+    private resolve?;
+    private currentAngle;
+    create(imageBase64: string): {
+        element: HTMLElement;
+        promise: Promise<RotateResult>;
+    };
+}

package/dist/types/challenges/slider.d.ts

@@ -0,0 +1,17 @@
+export interface SliderResult {
+    sliderX: number;
+    trajectory: any[];
+    passtime: number;
+}
+export declare class SliderChallenge {
+    private recorder;
+    private resolve?;
+    private targetX;
+    private cleanupFns;
+    create(targetX: number): {
+        element: HTMLElement;
+        promise: Promise<SliderResult>;
+    };
+    destroy(): void;
+    private setupDrag;
+}

package/dist/types/challenges/spatial.d.ts

@@ -0,0 +1,12 @@
+export interface SpatialResult {
+    answerIndex: number;
+    passtime: number;
+}
+export declare class SpatialChallenge {
+    private resolve?;
+    private startTime;
+    create(imageBase64: string, question: string, options: string[]): {
+        element: HTMLElement;
+        promise: Promise<SpatialResult>;
+    };
+}

package/dist/types/compat/hcaptcha.d.ts

@@ -0,0 +1 @@
+export declare function installHCaptchaCompat(apiBase: string): void;

package/dist/types/compat/recaptcha.d.ts

@@ -0,0 +1 @@
+export declare function installRecaptchaCompat(apiBase: string): void;

package/dist/types/crypto.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Communication security: AES-256-GCM encryption + HMAC-SHA256 signing.
+ * MVP uses a simplified approach with server-provided key material.
+ */
+export declare function encryptPayload(data: any, sessionKey: string): Promise<{
+    encrypted: string;
+    iv: string;
+    hmac: string;
+}>;
+export declare function createRequestSignature(method: string, path: string, body: string, timestamp: number, nonce: string, secretKey: string): Promise<string>;
+export declare function generateNonce(): string;

package/dist/types/deep_probes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Deep environment probes — counter Camoufox/Nodriver/Stealth attacks.
+ * These tests exploit behavioral and timing differences that are extremely
+ * difficult to fake even with C++-level browser patching.
+ */
+export interface DeepProbeResult {
+    name: string;
+    detected: boolean;
+    value: string;
+    weight: number;
+    confidence: number;
+}
+export declare function runDeepProbes(): Promise<DeepProbeResult[]>;

package/dist/types/degradation.d.ts

@@ -0,0 +1,27 @@
+export interface DegradationConfig {
+    maxRetries: number;
+    retryDelayMs: number;
+    fallbackMode: 'invisible' | 'local-pow' | 'always-pass';
+    healthCheckIntervalMs: number;
+}
+export declare class DegradationManager {
+    private config;
+    private isServerHealthy;
+    private consecutiveFailures;
+    private healthCheckTimer;
+    constructor(config?: Partial<DegradationConfig>);
+    executeWithRetry<T>(fn: () => Promise<T>): Promise<T | null>;
+    shouldDegrade(): boolean;
+    getDegradedResult(): {
+        success: boolean;
+        token: string;
+        degraded: boolean;
+    };
+    private localPoW;
+    private simpleHash;
+    startHealthCheck(healthFn: () => Promise<boolean>): void;
+    stopHealthCheck(): void;
+    private onSuccess;
+    private onFailure;
+    private delay;
+}

package/dist/types/device_attestation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Device Attestation — hardware-backed trust verification.
+ *
+ * Web: WebAuthn/FIDO2 for device binding
+ * The server can optionally require device attestation for high-risk scenarios.
+ */
+export interface AttestationResult {
+    supported: boolean;
+    type: 'webauthn' | 'none';
+    credential?: string;
+    attestationObject?: string;
+    clientDataJSON?: string;
+}
+export declare function checkDeviceAttestationSupport(): Promise<{
+    webauthn: boolean;
+    platformAuthenticator: boolean;
+    conditionalMediation: boolean;
+}>;
+export declare function requestDeviceAttestation(challenge: Uint8Array, rpId: string, userId: string): Promise<AttestationResult>;

package/dist/types/fingerprint.d.ts

@@ -0,0 +1,2 @@
+import { Fingerprint, FingerprintOptions } from './types';
+export declare function collectFingerprint(options?: FingerprintOptions): Promise<Fingerprint>;

package/dist/types/headless.d.ts

@@ -0,0 +1,2 @@
+import { HeadlessSignal } from './types';
+export declare function detectHeadless(): Promise<HeadlessSignal[]>;

package/dist/types/i18n.d.ts

@@ -0,0 +1,7 @@
+export type Locale = string;
+export declare function setLocale(locale: string): void;
+export declare function getLocale(): string;
+export declare function isRtl(): boolean;
+export declare function detectLocale(): string;
+export declare function registerLocale(locale: string, msgs: Record<string, string>): void;
+export declare function t(key: string): string;

package/dist/types/index.d.ts

@@ -0,0 +1,36 @@
+import { CaptchaConfig } from './types';
+import type { DeepProbeResult } from './deep_probes';
+export type { DeepProbeResult };
+export { DegradationManager, DegradationConfig } from './degradation';
+export declare class EngageLabCaptcha {
+    private config;
+    private api;
+    private container;
+    private sessionId;
+    private sdkInitTime;
+    private pageTrajectory;
+    private passiveCollector;
+    private nativeMonitor;
+    private sessionPersist;
+    private escalationDepth;
+    private cachedCollectedData;
+    private static readonly MAX_ESCALATION_DEPTH;
+    constructor(config: CaptchaConfig);
+    execute(challengeType?: string): Promise<void>;
+    private runChallenge;
+    reset(): void;
+    destroy(): void;
+    private collectAllData;
+    private runInvisible;
+    private runSlider;
+    private runSpatial;
+    private runRotate;
+    private runIcons;
+    private runDragSort;
+    private runGrid;
+    private runPhysics;
+    private handleResult;
+    private handleServiceUnavailable;
+}
+export { registerWebComponent, EngageLabCaptchaElement } from './web-component';
+export default EngageLabCaptcha;

package/dist/types/integrity.d.ts

@@ -0,0 +1,3 @@
+import { IntegrityData } from './types';
+export declare function checkIntegrity(): IntegrityData;
+export declare function setFunctionRefs(fp: Function, hl: Function, pow: Function): void;

package/dist/types/logger.d.ts

@@ -0,0 +1,49 @@
+/**
+ * EngageLab CAPTCHA SDK Logger
+ *
+ * Provides structured logging with levels and optional console output.
+ * Can be enabled via config or localStorage for debugging.
+ */
+export declare enum LogLevel {
+    NONE = 0,
+    ERROR = 1,
+    WARN = 2,
+    INFO = 3,
+    DEBUG = 4
+}
+interface LogEntry {
+    timestamp: number;
+    level: string;
+    module: string;
+    message: string;
+    data?: any;
+}
+declare class SDKLogger {
+    private level;
+    private logs;
+    private maxLogs;
+    private prefix;
+    private apiBase;
+    private siteKey;
+    private sessionId;
+    private flushTimer;
+    private isFlushing;
+    setLevel(level: LogLevel): void;
+    enableDebug(): void;
+    disable(): void;
+    error(module: string, message: string, data?: any): void;
+    warn(module: string, message: string, data?: any): void;
+    info(module: string, message: string, data?: any): void;
+    debug(module: string, message: string, data?: any): void;
+    getLogs(): LogEntry[];
+    clearLogs(): void;
+    private log;
+    configure(apiBase: string, siteKey: string): void;
+    setSessionId(id: string): void;
+    startAutoFlush(intervalMs?: number): void;
+    stopAutoFlush(): void;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+export declare const sdkLogger: SDKLogger;
+export {};

package/dist/types/native_monitor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * NativeMonitor — wrap sensitive global functions to detect automation tool injection.
+ *
+ * Records stack traces from calls to eval, Function constructor, and setTimeout(string).
+ * Provides disable() and a config flag (disableEvalPatching) for environments
+ * where wrapping interferes with HMR or dev tooling.
+ */
+import type { NativeTrace } from './types';
+export declare class NativeMonitor {
+    private traces;
+    private originals;
+    private active;
+    start(): void;
+    disable(): void;
+    getTraces(): NativeTrace[];
+    private record;
+    private wrapEval;
+    private wrapFunctionConstructor;
+    private wrapSetTimeoutString;
+    private restore;
+}

package/dist/types/passive_signals.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Passive Signal Collection — detect bots through background behavioral analysis.
+ * These signals are collected BEFORE the user interacts with any challenge.
+ */
+export interface DeviceMotionResult {
+    sampleCount: number;
+    avgAcceleration: number;
+    stdAcceleration: number;
+    avgRotationRate: number;
+    stdRotationRate: number;
+    hasGravity: boolean;
+}
+export interface DeviceOrientationResult {
+    sampleCount: number;
+    avgGammaDelta: number;
+    avgBetaDelta: number;
+    hasData: boolean;
+}
+export interface PassiveSignalResult {
+    rafTiming: RafTimingResult;
+    hoverTrap: HoverTrapResult;
+    eventTiming: EventTimingResult;
+    scrollBehavior: ScrollBehaviorResult;
+    idlePattern: IdlePatternResult;
+    inputBehavior: InputBehaviorResult;
+    deviceMotion?: DeviceMotionResult;
+    deviceOrientation?: DeviceOrientationResult;
+}
+interface RafTimingResult {
+    avgInterval: number;
+    stdInterval: number;
+    minInterval: number;
+    maxInterval: number;
+    frameCount: number;
+    anomaly: boolean;
+    anomalyType: string;
+}
+interface HoverTrapResult {
+    triggered: boolean;
+    hoverCount: number;
+    mouseOverHidden: boolean;
+}
+interface EventTimingResult {
+    mousedownToMouseup: number[];
+    mousemoveToClick: number;
+    avgClickDuration: number;
+    hasNaturalVariance: boolean;
+}
+interface ScrollBehaviorResult {
+    scrollEvents: number;
+    hasInertia: boolean;
+    avgScrollDelta: number;
+    scrollPatternRegular: boolean;
+}
+interface IdlePatternResult {
+    idlePeriods: number;
+    avgIdleDuration: number;
+    hasNaturalPauses: boolean;
+}
+interface InputBehaviorResult {
+    keyPressIntervals: number[];
+    hasTypingRhythm: boolean;
+    avgKeyInterval: number;
+    keystrokeDynamics: KeystrokeDynamics;
+}
+interface KeystrokeDynamics {
+    dwellTimes: number[];
+    flightTimes: number[];
+    avgDwell: number;
+    avgFlight: number;
+    dwellVariance: number;
+    flightVariance: number;
+    digraphLatencies: Record<string, number[]>;
+}
+export declare class PassiveSignalCollector {
+    private rafTimings;
+    private lastRafTime;
+    private rafHandle;
+    private mouseEvents;
+    private scrollEvents;
+    private keyEvents;
+    private hoverTrapTriggered;
+    private hoverTrapElement;
+    private idlePeriods;
+    private lastActivityTime;
+    private collecting;
+    private motionSamples;
+    private motionHasGravity;
+    private orientationDeltas;
+    private lastGamma;
+    private lastBeta;
+    private isMobileDevice;
+    start(): void;
+    stop(): void;
+    getResults(): PassiveSignalResult;
+    private measureRaf;
+    private analyzeRafTiming;
+    private setupHoverTrap;
+    private removeHoverTrap;
+    private analyzeHoverTrap;
+    private onMouseEvent;
+    private onScrollEvent;
+    private onKeyDown;
+    private onKeyUp;
+    private recordActivity;
+    private attachListeners;
+    private detachListeners;
+    private analyzeEventTiming;
+    private analyzeScrollBehavior;
+    private analyzeIdlePattern;
+    private analyzeInputBehavior;
+    private onDeviceMotion;
+    private onDeviceOrientation;
+    private startDeviceSensors;
+    private stopDeviceSensors;
+    private analyzeDeviceMotion;
+    private analyzeDeviceOrientation;
+}
+export {};

package/dist/types/pow.d.ts

@@ -0,0 +1,2 @@
+import { PowResult } from './types';
+export declare function computePoW(challenge: string, difficulty: number): Promise<PowResult>;

package/dist/types/reporter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error reporting and performance monitoring for the SDK.
+ * Collects exceptions and performance metrics, sends via beacon.
+ */
+export declare function initReporter(endpoint: string, key: string): void;
+export declare function reportError(error: Error, context?: Record<string, string | number>): void;
+export declare function reportPerf(metric: string, durationMs: number): void;
+export declare function destroyReporter(): void;

package/dist/types/session_persist.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export interface SessionData {
+    sessionCount: number;
+    lastVerifyTime: number;
+    fingerprintHash: string;
+}
+export declare class SessionPersist {
+    private db;
+    private data;
+    load(): Promise<SessionData>;
+    recordVerify(fingerprintHash: string): Promise<void>;
+    getData(): SessionData;
+}

package/dist/types/theme.d.ts

@@ -0,0 +1,11 @@
+export interface CaptchaTheme {
+    primaryColor?: string;
+    successColor?: string;
+    errorColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderRadius?: number;
+    fontFamily?: string;
+}
+export declare function setTheme(theme: CaptchaTheme): void;
+export declare function getTheme(): Required<CaptchaTheme>;

package/dist/types/timing.d.ts

@@ -0,0 +1,2 @@
+import { TimingData } from './types';
+export declare function collectTimingData(sdkInitTime: number): TimingData;

package/dist/types/trajectory.d.ts

@@ -0,0 +1,18 @@
+import { TrajectoryPoint } from './types';
+export declare class TrajectoryRecorder {
+    private points;
+    private recording;
+    private element;
+    private handlers;
+    start(element: HTMLElement): void;
+    stop(): TrajectoryPoint[];
+    getPoints(): TrajectoryPoint[];
+    private bindEvents;
+    private unbindEvents;
+    private addPoint;
+    private onMouseMove;
+    private onMouseDown;
+    private onMouseUp;
+    private onClick;
+    private onTouchEvent;
+}