@keverdjs/fraud-sdk 1.0.0 → 2.0.0

package/README.md

@@ -2,6 +2,15 @@
 
 Vanilla JavaScript SDK for Keverd fraud detection and device fingerprinting. Works in any JavaScript environment (browser, Node.js, etc.).
 
+## ✨ Features
+
+- **Custom Fingerprinting System**: Built from scratch with 15+ fingerprint collectors (no external dependencies)
+- **Stable Visitor ID**: Deterministic device identification across browsers
+- **Behavioral Biometrics**: Typing patterns, mouse movements, swipe gestures
+- **Privacy Signals**: Incognito mode, VPN, automation detection
+- **Use-Case Specific**: Login, checkout, registration, password reset, account change verification
+- **Zero Dependencies**: No external libraries required
+
 ## Installation
 
 ```bash
@@ -32,7 +41,6 @@ import { Keverd } from '@keverdjs/fraud-sdk';
 // Initialize with configuration
 Keverd.init({
   apiKey: 'your-api-key',
-  endpoint: 'https://app.keverd.com', // Optional
   debug: true, // Optional: enable debug logging
 });
 
@@ -57,7 +65,6 @@ Keverd.init('your-api-key');
 // With options
 Keverd.init({
   apiKey: 'your-api-key',
-  endpoint: 'https://app.keverd.com',
   userId: 'optional-user-id',
   debug: false
 });

package/dist/collectors/audio-fingerprint.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Audio Fingerprint Collector
+ * Generates audio context fingerprint using oscillator analysis and frequency response
+ * This is a powerful technique for device identification
+ */
+export interface AudioFingerprint {
+    value: number;
+    duration: number;
+}
+export declare class AudioFingerprintCollector {
+    private cachedFingerprint;
+    /**
+     * Generate audio fingerprint
+     * Returns null if audio context is not available
+     */
+    collect(): Promise<AudioFingerprint | null>;
+    /**
+     * Calculate fingerprint from audio data
+     */
+    private calculateFingerprint;
+    /**
+     * Get fallback fingerprint when audio processing fails
+     */
+    private getFallbackFingerprint;
+    /**
+     * Clear cached fingerprint
+     */
+    clearCache(): void;
+}

package/dist/collectors/battery-api.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Battery API Collector
+ * Collects battery level, charging status, charging time (if available, with fallbacks)
+ * Note: Battery API is deprecated but still available in some browsers
+ */
+export interface BatteryFingerprint {
+    level: number | null;
+    charging: boolean | null;
+    chargingTime: number | null;
+    dischargingTime: number | null;
+    duration: number;
+}
+export declare class BatteryAPICollector {
+    private cachedFingerprint;
+    /**
+     * Collect battery information
+     * Returns null if Battery API is not available
+     */
+    collect(): Promise<BatteryFingerprint | null>;
+    /**
+     * Get battery manager from various API locations
+     */
+    private getBatteryManager;
+    /**
+     * Clear cached fingerprint
+     */
+    clearCache(): void;
+}

package/dist/collectors/behavioral.d.ts

@@ -1,71 +1,39 @@
-/**
- * Behavioral Data Collector
- * Collects typing patterns, mouse movements, swipe gestures, and calculates session entropy
- * Matches React SDK implementation for consistency
- */
 import { BehavioralData } from '../types';
 export declare class BehavioralCollector {
-    private keystrokes;
-    private mouseMovements;
-    private lastKeyDownTime;
-    private lastKeyUpTime;
     private isActive;
-    private sessionStartTime;
-    private typingDwellTimes;
-    private typingFlightTimes;
-    private swipeVelocities;
     private sessionEvents;
-    private touchStartPositions;
-    private keyDownHandler;
-    private keyUpHandler;
-    private mouseMoveHandler;
-    private touchStartHandler;
-    private touchEndHandler;
-    /**
-     * Start collecting behavioral data
-     * Uses passive listeners for efficiency (non-blocking)
-     */
+    private kinematicEngine;
+    private keystrokeMonitor;
+    constructor();
     start(): void;
-    /**
-     * Stop collecting behavioral data
-     */
     stop(): void;
-    /**
-     * Get collected behavioral data
-     * Returns data in format expected by backend
-     */
-    getData(): BehavioralData;
-    /**
-     * Reset collected data
-     */
     reset(): void;
-    /**
-     * Handle keydown event
-     */
-    private handleKeyDown;
-    /**
-     * Handle keyup event
-     */
-    private handleKeyUp;
-    /**
-     * Handle mouse move event
-     */
-    private handleMouseMove;
-    /**
-     * Handle touch start (for swipe detection)
-     */
-    private handleTouchStart;
-    /**
-     * Handle touch end (calculate swipe velocity)
-     */
-    private handleTouchEnd;
-    /**
-     * Calculate session entropy based on event diversity
-     * Uses Shannon entropy formula as expected by backend
-     */
+    getData(): BehavioralData;
+    private buildSequence;
+    private trackEvent;
     private calculateSessionEntropy;
     /**
-     * Check if key should be ignored
-     */
-    private shouldIgnoreKey;
+     * Get mouse signals from kinematic engine
+     */
+    getMouseSignals(): {
+        totalDistance: number;
+        averageVelocity: number;
+        clickCount: number;
+        rightClickCount: number;
+        doubleClickCount: number;
+        scrollDistance: number;
+        scrollDirection: "up" | "down" | "both";
+        touchEvents: number;
+    };
+    /**
+     * Get keyboard signals from keystroke monitor
+     */
+    getKeyboardSignals(): {
+        keydownCount: number;
+        keyupCount: number;
+        specialKeyCount: number;
+        typingSpeed: number;
+        pauseCount: number;
+        backspaceRatio: number;
+    };
 }

package/dist/collectors/browser-capabilities.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser Capability Collector
+ * Collects browser API availability and capabilities
+ */
+export interface BrowserCapabilities {
+    hasWebGL: boolean;
+    hasCanvas: boolean;
+    hasWebRTC: boolean;
+    hasServiceWorker: boolean;
+    hasIndexedDB: boolean;
+    hasLocalStorage: boolean;
+    hasSessionStorage: boolean;
+    cookieEnabled: boolean;
+    doNotTrack: boolean;
+}
+export declare class BrowserCapabilityCollector {
+    private cachedCapabilities;
+    /**
+     * Collect all browser capabilities
+     */
+    collect(): BrowserCapabilities;
+    private checkWebGL;
+    private checkCanvas;
+    private checkWebRTC;
+    private checkServiceWorker;
+    private checkIndexedDB;
+    private checkLocalStorage;
+    private checkSessionStorage;
+    /**
+     * Clear cached capabilities (useful for testing)
+     */
+    clearCache(): void;
+}

package/dist/collectors/canvas-fingerprint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Canvas Fingerprint Collector
+ * Generates a stable canvas fingerprint using text rendering, shapes, and gradients
+ * This is a key component for device identification
+ */
+export interface CanvasFingerprint {
+    value: string;
+    duration: number;
+}
+export declare class CanvasFingerprintCollector {
+    private cachedFingerprint;
+    /**
+     * Generate canvas fingerprint
+     * Returns null if canvas is not available
+     */
+    collect(): CanvasFingerprint | null;
+    /**
+     * Hash a string to create a stable fingerprint
+     */
+    private hashString;
+    /**
+     * Clear cached fingerprint
+     */
+    clearCache(): void;
+}

package/dist/collectors/cpu-memory.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CPU & Memory Collector
+ * Collects hardwareConcurrency, deviceMemory, performance.memory (if available)
+ */
+export interface CPUMemoryFingerprint {
+    hardwareConcurrency: number;
+    deviceMemory: number | null;
+    performanceMemory: {
+        jsHeapSizeLimit: number | null;
+        totalJSHeapSize: number | null;
+        usedJSHeapSize: number | null;
+    };
+    duration: number;
+}
+export declare class CPUMemoryCollector {
+    private cachedFingerprint;
+    /**
+     * Collect CPU and memory information
+     */
+    collect(): CPUMemoryFingerprint;
+    /**
+     * Get device memory (if available)
+     */
+    private getDeviceMemory;
+    /**
+     * Get performance memory information (Chrome-specific)
+     */
+    private getPerformanceMemory;
+    /**
+     * Clear cached fingerprint
+     */
+    clearCache(): void;
+}

package/dist/collectors/fingerprint-manager.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Fingerprint Component Manager
+ * Orchestrates all fingerprint collectors, handles caching, error recovery, and component weighting
+ * This is the main entry point for custom fingerprinting (replaces FingerprintJS)
+ */
+import { FingerprintData } from '../types/fingerprint';
+export declare class FingerprintManager {
+    private collectors;
+    private visitorIDGenerator;
+    private cachedData;
+    private collectionStartTime;
+    constructor();
+    /**
+     * Collect all fingerprint data
+     * This is the main method that replaces FingerprintJS.get()
+     */
+    collect(): Promise<FingerprintData>;
+    /**
+     * Get visitor ID only (faster, uses cached data if available)
+     */
+    getVisitorId(): Promise<string>;
+    /**
+     * Clear all cached data
+     */
+    clearCache(): void;
+    /**
+     * Get collection statistics
+     */
+    getStats(): {
+        componentsCollected: number;
+        totalComponents: number;
+        collectionTime: number;
+    };
+}

package/dist/collectors/fingerprintjs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @deprecated This collector is deprecated. Use FingerprintManager instead.
+ * This file is kept for backward compatibility but is no longer used.
+ *
+ * The SDK now uses custom fingerprinting modules (FingerprintManager) that
+ * collect all necessary data without external dependencies.
+ */
+export interface FingerprintJSData {
+    visitorId: string;
+    confidence?: number;
+    components?: Record<string, any>;
+}
+export declare class FingerprintJSCollector {
+    collect(): Promise<FingerprintJSData | null>;
+    clearCache(): void;
+    isAvailable(): Promise<boolean>;
+}

package/dist/collectors/font-detection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Font Detection Collector
+ * Detects installed fonts using font measurement techniques and fallback detection
+ * This helps identify unique system configurations
+ */
+export interface FontFingerprint {
+    availableFonts: string[];
+    missingFonts: string[];
+    duration: number;
+}
+export declare class FontDetectionCollector {
+    private cachedFingerprint;
+    private readonly testFonts;
+    /**
+     * Detect available fonts
+     * Returns null if detection fails
+     */
+    collect(): FontFingerprint | null;
+    /**
+     * Clear cached fingerprint
+     */
+    clearCache(): void;
+}

package/dist/collectors/form-interactions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Form Interaction Collector
+ * Tracks form field interactions: focus/blur, copy/paste, autofill, etc.
+ */
+export interface FormInteractions {
+    focusCount: number;
+    blurCount: number;
+    copyCount: number;
+    pasteCount: number;
+    cutCount: number;
+    autofillDetected: boolean;
+    autocompleteDetected: boolean;
+    fieldFocusOrder: string[];
+    timePerField: Record<string, number>;
+    backspaceCount: number;
+    deleteCount: number;
+}
+export declare class FormInteractionCollector {
+    private focusCount;
+    private blurCount;
+    private copyCount;
+    private pasteCount;
+    private cutCount;
+    private fieldFocusOrder;
+    private fieldFocusTimes;
+    private backspaceCount;
+    private deleteCount;
+    private autofillDetected;
+    private autocompleteDetected;
+    private isActive;
+    private focusHandler;
+    private blurHandler;
+    private copyHandler;
+    private pasteHandler;
+    private cutHandler;
+    private keydownHandler;
+    private inputHandler;
+    /**
+     * Start collecting form interactions
+     */
+    start(): void;
+    /**
+     * Stop collecting form interactions
+     */
+    stop(): void;
+    /**
+     * Get collected form interaction data
+     */
+    getData(): FormInteractions;
+    /**
+     * Reset all collected data
+     */
+    reset(): void;
+    private handleFocus;
+    private handleBlur;
+    private handleCopy;
+    private handlePaste;
+    private handleCut;
+    private handleKeyDown;
+    private handleInput;
+    private isFormField;
+    private getFieldId;
+}

package/dist/collectors/hardware-signals.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hardware Signal Collector
+ * Collects hardware and network information
+ */
+export interface HardwareSignals {
+    hardwareConcurrency: number;
+    deviceMemory: number | null;
+    maxTouchPoints: number;
+    connectionType: string | null;
+    effectiveType: string | null;
+    downlink: number | null;
+    rtt: number | null;
+    saveData: boolean | null;
+}
+export declare class HardwareSignalCollector {
+    private cachedSignals;
+    /**
+     * Collect all hardware signals
+     */
+    collect(): HardwareSignals;
+    private getDeviceMemory;
+    private getConnectionType;
+    private getEffectiveType;
+    private getDownlink;
+    private getRTT;
+    private getSaveData;
+    /**
+     * Clear cached signals (useful for testing)
+     */
+    clearCache(): void;
+}

package/dist/collectors/keystroke-monitor.d.ts

@@ -0,0 +1,49 @@
+import { KeystrokeFeatureVector } from '../types';
+type KeystrokeMonitorEvent = 'keydown' | 'keyup';
+interface KeystrokeMonitorOptions {
+    onEvent?: (event: KeystrokeMonitorEvent) => void;
+}
+export declare class KeystrokeMonitor {
+    private keyDownTimes;
+    private lastKeyUpTime;
+    private lastKeyDownTime;
+    private featureVectors;
+    private dwellTimes;
+    private flightTimes;
+    private digraphLatencies;
+    private isActive;
+    private onEvent?;
+    private keydownCount;
+    private keyupCount;
+    private specialKeyCount;
+    private lastKeystrokeTime;
+    private pauseCount;
+    private PAUSE_THRESHOLD;
+    private keystrokeTimestamps;
+    private keyDownHandler;
+    private keyUpHandler;
+    constructor(options?: KeystrokeMonitorOptions);
+    start(): void;
+    stop(): void;
+    getVectors(): KeystrokeFeatureVector[];
+    getDwellTimes(limit?: number): number[];
+    getFlightTimes(limit?: number): number[];
+    /**
+     * Get enhanced keyboard signals
+     */
+    getKeyboardSignals(): {
+        keydownCount: number;
+        keyupCount: number;
+        specialKeyCount: number;
+        typingSpeed: number;
+        pauseCount: number;
+        backspaceRatio: number;
+    };
+    private getBackspaceCount;
+    reset(): void;
+    private handleKeyDown;
+    private handleKeyUp;
+    private appendVector;
+    private isTargetField;
+}
+export {};

package/dist/collectors/kinematic-engine.d.ts

@@ -0,0 +1,66 @@
+import { KinematicFeatureVector } from '../types';
+export type KinematicEngineEvent = 'mousemove' | 'mousedown' | 'mouseup';
+interface KinematicEngineOptions {
+    onEvent?: (event: KinematicEngineEvent) => void;
+    maskValue?: number;
+}
+export declare class KinematicEngine {
+    private featureVectors;
+    private pointerQueue;
+    private lastVelocity;
+    private lastAcceleration;
+    private lastAngle;
+    private lastPoint;
+    private secondLastPoint;
+    private rafId;
+    private maxSwipeVelocity;
+    private onEvent?;
+    private maskValue;
+    private isActive;
+    private clickCount;
+    private rightClickCount;
+    private doubleClickCount;
+    private totalMouseDistance;
+    private lastClickTime;
+    private scrollDistance;
+    private lastScrollTop;
+    private touchEventCount;
+    private mouseMoveHandler;
+    private mouseDownHandler;
+    private mouseUpHandler;
+    private contextMenuHandler;
+    private scrollHandler;
+    private touchStartHandler;
+    private touchMoveHandler;
+    private touchEndHandler;
+    constructor(options?: KinematicEngineOptions);
+    start(): void;
+    stop(): void;
+    getVectors(): KinematicFeatureVector[];
+    getSuspiciousSwipeVelocity(): number;
+    /**
+     * Get enhanced mouse/touch signals
+     */
+    getMouseSignals(): {
+        totalDistance: number;
+        averageVelocity: number;
+        clickCount: number;
+        rightClickCount: number;
+        doubleClickCount: number;
+        scrollDistance: number;
+        scrollDirection: 'up' | 'down' | 'both';
+        touchEvents: number;
+    };
+    reset(): void;
+    private enqueuePoint;
+    private scheduleProcess;
+    private processQueue;
+    private computeFeatures;
+    private calculateCurvature;
+    private normalizeAngle;
+    private handleClick;
+    private handleRightClick;
+    private handleScroll;
+    private handleTouch;
+}
+export {};

package/dist/collectors/media-devices.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Media Devices Collector
+ * Lists audio/video devices and enumerates media devices with labels
+ * Requires user permission for device labels
+ */
+export interface MediaDeviceFingerprint {
+    audioInputs: MediaDeviceInfo[];
+    audioOutputs: MediaDeviceInfo[];
+    videoInputs: MediaDeviceInfo[];
+    hasPermission: boolean;
+    duration: number;
+}
+export declare class MediaDevicesCollector {
+    private cachedFingerprint;
+    /**
+     * Collect media device information
+     * Returns null if MediaDevices API is not available
+     */
+    collect(): Promise<MediaDeviceFingerprint | null>;
+    /**
+     * Clear cached fingerprint
+     */
+    clearCache(): void;
+}

package/dist/collectors/page-interactions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Page Interaction Collector
+ * Tracks page-level interactions: load time, scroll depth, clicks, etc.
+ */
+export interface PageInteractions {
+    pageLoadTime: number;
+    timeToFirstInteraction: number;
+    timeOnPage: number;
+    scrollDepth: number;
+    clickCount: number;
+    linkClickCount: number;
+    imageViewCount: number;
+    videoPlayCount: number;
+}
+export declare class PageInteractionCollector {
+    private pageLoadTime;
+    private timeToFirstInteraction;
+    private startTime;
+    private firstInteractionTime;
+    private maxScrollDepth;
+    private clickCount;
+    private linkClickCount;
+    private imageViewCount;
+    private videoPlayCount;
+    private isActive;
+    private clickHandler;
+    private scrollHandler;
+    private loadHandler;
+    private imageLoadHandler;
+    private videoPlayHandler;
+    constructor();
+    /**
+     * Start collecting page interactions
+     */
+    start(): void;
+    /**
+     * Stop collecting page interactions
+     */
+    stop(): void;
+    /**
+     * Get collected page interaction data
+     */
+    getData(): PageInteractions;
+    /**
+     * Reset all collected data
+     */
+    reset(): void;
+    private handleLoad;
+    private handleClick;
+    private handleScroll;
+    private handleImageLoad;
+    private handleVideoPlay;
+    private calculateScrollDepth;
+}

package/dist/collectors/permissions-api.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Permissions API Collector
+ * Checks permissions for camera, microphone, notifications, geolocation
+ */
+export interface PermissionsFingerprint {
+    camera: string | null;
+    microphone: string | null;
+    notifications: string | null;
+    geolocation: string | null;
+    persistentStorage: string | null;
+    duration: number;
+}
+export declare class PermissionsAPICollector {
+    private cachedFingerprint;
+    /**
+     * Collect permission states
+     * Returns null if Permissions API is not available
+     */
+    collect(): Promise<PermissionsFingerprint | null>;
+    /**
+     * Query a specific permission
+     */
+    private queryPermission;
+    /**
+     * Clear cached fingerprint
+     */
+    clearCache(): void;
+}