@ginger-ai/ginger-js 0.0.1

package/src/device/factory.ts

@@ -0,0 +1,54 @@
+import { options } from './modules/options';
+
+// the component interface is the form of the JSON object the function's promise must return
+export interface componentInterface {
+    [key: string]: string | string[] | number | boolean | componentInterface;
+}
+
+
+// The component function's interface is simply the promise of the above
+export interface componentFunctionInterface {
+    (): Promise<componentInterface>;
+}
+
+// components include a dictionary of name: function.
+export const components: {[name: string]: componentFunctionInterface} = {};
+
+
+/** 
+ * includeComponent is the function each component function needs to call in order for the component to be included
+ * in the fingerprint.
+ * @param {string} name - the name identifier of the component
+ * @param {componentFunctionInterface} creationFunction - the function that implements the component
+ * @returns 
+ */ 
+export const includeComponent = (name:string, creationFunction: componentFunctionInterface) => {
+    if (typeof window !== 'undefined')
+        components[name] = creationFunction;
+}
+
+
+/**
+ * The function turns the map of component functions to a map of Promises when called
+ * @returns {[name: string]: <Promise>componentInterface} 
+ */
+export const getComponentPromises = () => {
+    return Object.fromEntries(
+        Object.entries(components)
+            .filter(([key]) => {
+                return !options?.exclude?.includes(key)}
+                )
+            .filter(([key]) => {
+                return options?.include?.some(e => e.includes('.'))
+                    ? options?.include?.some(e => e.startsWith(key))
+                    : options?.include?.length === 0 || options?.include?.includes(key)
+            }
+                    )
+            .map(([key, value]) => [key, value()])
+    );
+}
+
+
+export const timeoutInstance: componentInterface = {
+    'timeout': "true"
+}

package/src/device/index.ts

@@ -0,0 +1,60 @@
+import { getFingerprint } from './modules/fp'
+import { detectTorBrowser } from './modules/tor'
+import { detectIncognito } from './modules/incognito'
+import { botDetection } from './modules/bot'
+import { detectBrowser } from './components/system/browser'
+import { getOs } from './modules/os'
+import { getDeviceDetails } from './modules/device'
+import { getBrowserDetails } from './modules/browserDetails'
+import './components'
+
+export { getFingerprint, detectTorBrowser, detectIncognito, botDetection, detectBrowser, getOs, getDeviceDetails, getBrowserDetails }
+
+interface SdkInfo {
+  name: string;
+  version: string;
+}
+
+export const buildInitialPayload = async (request_id: string, sdkInfo: SdkInfo) => {
+  const [
+    fingerprint,
+    torResult,
+    botResult,
+    incognito,
+    osResult,
+    deviceDetails,
+    browserDetails,
+  ] = await fetchModules();
+
+  return {
+    request_id,
+    device: {
+      fingerprint_id: fingerprint.hash,
+      type: "web",
+      os: deviceDetails.deviceOs,
+      os_version: osResult.version,
+      raw_device_data: fingerprint.data,
+      browserDetails: browserDetails,
+      bot: botResult,
+      tampering: deviceDetails.tampering,
+      incognito: incognito,
+      tor: torResult,
+    },
+    sdk: {
+      name: sdkInfo?.name,
+      version: sdkInfo?.version
+    }
+  };
+};
+
+export async function fetchModules() {
+  return await Promise.all([
+    getFingerprint(),
+    detectTorBrowser(),
+    botDetection(),
+    detectIncognito(),
+    getOs(),
+    getDeviceDetails(),
+    getBrowserDetails(),
+  ]);
+}

package/src/device/modules/bot.ts

@@ -0,0 +1,25 @@
+import { load } from "@fingerprintjs/botd";
+
+async function botDetection() {
+  try {
+    const botd = await load();
+    const result = botd.detect();
+
+
+    if (result.bot) {
+      return {
+        status: true,
+        botKind: result.botKind,
+      };
+    } else {
+      return {
+        status: false,
+      };
+    }
+  } catch (error) {
+    console.error(error);
+    return null;
+  }
+}
+
+export { botDetection };

package/src/device/modules/browserDetails.ts

@@ -0,0 +1,11 @@
+import { detectBrowser } from "../components/system/browser";
+
+export async function getBrowserDetails() {
+  const { name, version } = detectBrowser();
+
+  return {
+    name,
+    version,
+    user_agent: navigator.userAgent,
+  };
+}

package/src/device/modules/device/analyze-data.ts

@@ -0,0 +1,150 @@
+import { DeviceResults, AllowedOs, DeviceType } from '../../../core';
+import { normalizeOs, determineDeviceType, convertToTwoDP, isAllowedDeviceType, detectActualOs } from './helpers';
+
+type ClaimedData = DeviceResults['claimed'];
+type SignalData = DeviceResults['signals'];
+type AnalysisData = DeviceResults['analysis'];
+
+export const analyzeSpoofing = (claimed: ClaimedData, signals: SignalData): AnalysisData => {
+  const MAX_CONFIDENCE_SCORE = 1.0;
+  let score = MAX_CONFIDENCE_SCORE;
+  const conflicts: string[] = [];
+  const analysis: AnalysisData = {
+      confidence: MAX_CONFIDENCE_SCORE,
+      spoofingConfidence: 0.0,
+      isSpoofed: false,
+      detectionConflicts: [],
+      realPlatform: null,
+      realDeviceType: null,
+  };
+
+  const hasTouch = signals.touchPoints > 0;
+  const screenWidth = signals.screen.width;
+
+  const claimedOs = normalizeOs(claimed.platform);
+  const gpuOs = detectActualOs(signals.webGL.renderer?.toLowerCase() || '');
+  const platformOs = normalizeOs(signals.actualPlatform);
+  const actualOs = gpuOs || platformOs;
+  let suspectedOs: AllowedOs | null = claimedOs;
+
+  // --- Apply Rules ---
+
+  // Rule 1: Os Mismatch
+  if (claimedOs && actualOs && claimedOs !== actualOs) {
+    score -= 0.3;
+    conflicts.push(`Claimed OS "${claimedOs}" disagrees with actual OS signal "${actualOs}".`);
+    suspectedOs = actualOs; // Trust actual signal more initially
+  } else if (claimedOs && !actualOs && claimed.platform !== '') {
+    score -= 0.2;
+    conflicts.push(`Actual OS signal "${signals.actualPlatform}" is unrecognized.`);
+    suspectedOs = claimedOs;
+  } else if (!claimedOs && actualOs) {
+    score -= 0.2;
+    conflicts.push(`Claimed OS signal "${claimed.platform}" is unrecognized.`);
+    suspectedOs = actualOs;
+  }
+
+  // Rule 2: GPU Vendor vs Determined Preliminary OS
+  const gpuVendor = (signals.webGL.vendor || "").toLowerCase();
+  const gpuRenderer = (signals.webGL.renderer || "").toLowerCase();
+
+  if (gpuVendor && gpuVendor !== 'n/a' && gpuVendor !== 'n/a (masked)') {
+    let gpuConflict = false;
+    let gpuSuggestedOs: AllowedOs | null = null;
+
+    if (suspectedOs === 'android' && (gpuVendor.includes('apple') || gpuRenderer.includes('apple'))) { gpuConflict = true; gpuSuggestedOs = 'ios'; }
+    else if (suspectedOs === 'ios' && !gpuVendor.includes('apple') && !gpuRenderer.includes('apple')) {
+        gpuConflict = true;
+        if (gpuVendor.includes('qualcomm') || gpuVendor.includes('adreno') || gpuVendor.includes('mali') || gpuVendor.includes('powervr') || gpuVendor.includes('arm')) { gpuSuggestedOs = 'android'; }
+        else if (gpuVendor.includes('intel') || gpuRenderer.includes('intel') || gpuVendor.includes('nvidia') || gpuRenderer.includes('nvidia') || gpuVendor.includes('amd') || gpuRenderer.includes('amd') || gpuRenderer.includes('radeon')) { gpuSuggestedOs = 'windows'; }
+        else { gpuSuggestedOs = 'android'; }
+    }
+    else if (suspectedOs === 'windows' && (gpuVendor.includes('apple') || gpuRenderer.includes('apple'))) { gpuConflict = true; gpuSuggestedOs = 'macos'; }
+    else if (suspectedOs === 'macos' && !(gpuVendor.includes('apple') || gpuRenderer.includes('apple') || gpuVendor.includes('intel') || gpuRenderer.includes('intel') || gpuVendor.includes('amd') || gpuRenderer.includes('amd') || gpuRenderer.includes('radeon'))) {
+        gpuConflict = true;
+        if (gpuVendor.includes('qualcomm') || gpuVendor.includes('adreno') || gpuVendor.includes('mali') || gpuVendor.includes('powervr') || gpuVendor.includes('arm')) { gpuSuggestedOs = 'android'; }
+        else { gpuSuggestedOs = 'windows'; }
+    }
+
+    if (gpuConflict) {
+      score -= 0.5;
+      conflicts.push(`OS "${suspectedOs}" conflicts with GPU "${signals.webGL.vendor} / ${signals.webGL.renderer}". GPU suggests "${gpuSuggestedOs || 'unknown'}".`);
+      if (gpuSuggestedOs) { suspectedOs = gpuSuggestedOs; }
+    }
+    // Add logic here for suspicious but not conflicting GPUs if desired (e.g., Intel GPU on Android)
+  } else if (signals.webGL.error) {
+    score -= 0.1;
+    conflicts.push(`WebGL info unavailable (${signals.webGL.error}).`);
+  }
+
+
+  // Rule 3: Claimed Device Type vs Touch Support
+  let preliminaryRealDeviceType: DeviceType | null = null;
+  const normalizedClaimedType = isAllowedDeviceType(claimed.guessedDeviceType) ? claimed.guessedDeviceType : null;
+
+  if (claimed.mobile === true && !hasTouch) {
+      score -= 0.3;
+      conflicts.push(`Claimed mobile=true but no touch points detected.`);
+      preliminaryRealDeviceType = 'desktop';
+  } else if (claimed.mobile === false && hasTouch) {
+      score -= 0.15;
+      conflicts.push(`Claimed mobile=false but touch points detected.`);
+      preliminaryRealDeviceType = determineDeviceType(claimed.mobile, hasTouch, screenWidth, suspectedOs);
+  } else if (normalizedClaimedType) {
+       // If claimed type exists and doesn't conflict strongly with touch, use it as preliminary
+       preliminaryRealDeviceType = normalizedClaimedType;
+  }
+
+
+  // Rule 4: Screen Size vs Preliminary Device Type Sanity Check
+  const typicalMobileWidth = 768;
+  const typicalTabletWidth = 1024;
+
+  if (preliminaryRealDeviceType === 'mobile' && screenWidth > typicalTabletWidth) {
+      score -= 0.15;
+      conflicts.push(`Device type 'mobile', but screen width (${screenWidth}px) is large.`);
+      preliminaryRealDeviceType = 'tablet';
+  } else if (preliminaryRealDeviceType === 'desktop' && screenWidth < typicalMobileWidth) {
+      score -= 0.15;
+      conflicts.push(`Preliminary type 'desktop', but screen width (${screenWidth}px) is small.`);
+      preliminaryRealDeviceType = hasTouch ? 'mobile' : 'desktop';
+  }
+
+  // --- Finalize Analysis ---
+  // We use the suspected Os but fallback to the claimed os of the ua if null
+  analysis.realPlatform = suspectedOs || claimedOs;
+
+  // Determine final device type
+  const determinedType = determineDeviceType(claimed.mobile, hasTouch, screenWidth, analysis.realPlatform);
+
+  if (!preliminaryRealDeviceType) {
+       analysis.realDeviceType = determinedType;
+  } else {
+       // Check if the determined type based on final signals contradicts the preliminary one
+       if (determinedType && determinedType !== preliminaryRealDeviceType) {
+           score -= 0.12; // Small penalty for internal inconsistency
+           conflicts.push(`Initial device type guess (${preliminaryRealDeviceType}) adjusted to ${determinedType} based on final signals.`);
+           analysis.realDeviceType = determinedType;
+       } else {
+            analysis.realDeviceType = preliminaryRealDeviceType;
+       }
+  }
+
+   // Ensure device type is populated based on OS if still null
+   if (!analysis.realDeviceType) {
+       if (analysis.realPlatform === 'ios' || analysis.realPlatform === 'android') {
+           analysis.realDeviceType = determinedType || 'mobile';
+       } else if (analysis.realPlatform) { // windows, macos, linux
+            analysis.realDeviceType = determinedType || 'desktop';
+       } else { // OS unknown
+           analysis.realDeviceType = hasTouch ? (screenWidth > 768 ? 'tablet' : 'mobile') : 'desktop';
+       }
+   }
+
+  analysis.confidence = convertToTwoDP(Math.max(0, score));
+  analysis.spoofingConfidence = convertToTwoDP(MAX_CONFIDENCE_SCORE - analysis.confidence);
+  analysis.isSpoofed = analysis.spoofingConfidence > 0.1;
+  analysis.detectionConflicts = conflicts;
+
+  return analysis;
+};

package/src/device/modules/device/gather-data.ts

@@ -0,0 +1,92 @@
+import { DeviceResults, ClaimedDevice } from '../../../core';
+import { guessDeviceTypeFromUA } from './helpers';
+
+
+type SignalData = DeviceResults['signals'];
+
+// What the device claims to be is gotten from the useragent string
+export const getClaimedData = async (userAgentString: string): Promise<ClaimedDevice> => {
+  const claimed = {} as ClaimedDevice;
+
+  try {
+    if ((navigator as any).userAgentData) {
+      const uaData = await (navigator as any).userAgentData.getHighEntropyValues([
+        "platform", "platformVersion", "architecture", "model", "uaFullVersion", "brands", "mobile",
+      ]);
+      claimed.platform = uaData.platform;
+      claimed.mobile = uaData.mobile ?? null;
+      claimed.brands = uaData.brands || [];
+
+      // Initial guess - will be refined later using signals if needed
+      if (claimed.mobile) {
+           claimed.guessedDeviceType = screen.width > 768 ? "tablet" : "mobile";
+      } else {
+          claimed.guessedDeviceType = "desktop";
+      }
+    } else {
+      const ua = userAgentString;
+      const lowerUa = ua.toLowerCase();
+
+      // Determine the device platform from user agent string
+      if (lowerUa.includes("android")) claimed.platform = "Android";
+      else if (lowerUa.includes("iphone") || lowerUa.includes("ipad")) claimed.platform = "iOS";
+      else if (lowerUa.includes("windows nt")) claimed.platform = "Windows";
+      else if (lowerUa.includes("mac os x") || lowerUa.includes("macintosh")) claimed.platform = "macOS";
+      else if (lowerUa.includes("linux")) claimed.platform = "Linux";
+
+      const guessedType = guessDeviceTypeFromUA(ua);
+      claimed.guessedDeviceType = guessedType;
+      claimed.mobile = guessedType === 'mobile' || guessedType === 'tablet';
+
+      const brandMatch = ua.match(/(Apple|Samsung|Google|Microsoft|Sony|LG|HTC|Nokia|Motorola|Huawei|Xiaomi|Pixel|Firefox|Safari|Edge|Chrome)/i);
+      if (brandMatch) {
+        const versionMatch = ua.match(new RegExp(brandMatch[0] + "[ /]([\\d._]+)"));
+        claimed.brands.push({ brand: brandMatch[0], version: versionMatch ? versionMatch[1] : "unknown" });
+      }
+    }
+  } catch (e) {
+    console.error("Error getting User Agent Data:", e);
+  }
+  return claimed;
+};
+
+// What we actually think the device could be achieved from some of this signals
+export const getSignalData = (): SignalData => {
+  const signals: SignalData = {
+    actualPlatform: (navigator as any).userAgentData?.platform || navigator.platform ,
+    touchPoints: navigator.maxTouchPoints || 0,
+    screen: {
+      width: screen.width,
+      height: screen.height,
+      pixelRatio: window.devicePixelRatio || 1,
+    },
+    webGL: { vendor: undefined, renderer: undefined, error: "" },
+    userAgentString: navigator.userAgent,
+  };
+
+  try {
+    const canvas = document.createElement("canvas");
+    const gl = canvas.getContext("webgl2") || canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
+
+    if (gl && 'getParameter' in gl) {
+      const debugInfo = gl.getExtension("WEBGL_debug_renderer_info");
+      if (debugInfo) {
+        signals.webGL.vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL) || "n/a";
+        signals.webGL.renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) || "n/a";
+      } else {
+        signals.webGL.vendor = gl.getParameter(gl.VENDOR) || "n/a (masked)";
+        signals.webGL.renderer = gl.getParameter(gl.RENDERER) || "n/a (masked)";
+        if (!signals.webGL.vendor || signals.webGL.vendor === "n/a (masked)") {
+             signals.webGL.error = "Debug info extension unavailable or vendor masked";
+        }
+      }
+    } else {
+      signals.webGL.error = "WebGL context unavailable";
+    }
+  } catch (error) {
+    console.error("Error getting WebGL data:", error);
+    signals.webGL.error = error instanceof Error ? error.message : "Unknown WebGL error";
+  }
+
+  return signals;
+};

package/src/device/modules/device/helpers.ts

@@ -0,0 +1,123 @@
+import {
+  ALLOWED_DEVICE_TYPES,
+  ALLOWED_OS,
+  AllowedOs,
+  DeviceType,
+} from '../../../core';
+
+// Normalize the gueesed Os
+export const normalizeOs = (
+  platform: string | undefined | null
+): AllowedOs | null => {
+  if (!platform) return null;
+  const lowerPlatform = platform.toLowerCase();
+
+  if (lowerPlatform.includes("android")) return "android";
+  if (
+    lowerPlatform.includes("iphone") ||
+    lowerPlatform.includes("ipad") ||
+    lowerPlatform === "ios"
+  )
+    return "ios";
+  if (lowerPlatform.includes("win")) return "windows";
+  if (lowerPlatform.includes("mac") || lowerPlatform.includes("macos"))
+    return "macos";
+  if (lowerPlatform.includes("linux")) return "linux";
+  // if (lowerPlatform.includes("cros")) return "linux"; // Example extension
+
+  return null;
+};
+
+const patterns = {
+  ios: [/apple a\d+ gpu/i],
+  macos: [/apple m\d+/i, /opengl engine/i],
+  windows: [/angle.*direct3d/i],
+  android: [/adreno|mali|powervr/i],
+  linux: [/mesa|x11/i],
+};
+
+// Detect the actual OS from the GPU vendor and renderer if available
+export const detectActualOs = (renderer: string): AllowedOs | null => {
+  if (patterns.ios.some((pattern) => pattern.test(renderer))) {
+    return "ios";
+  } else if (patterns.macos.some((pattern) => pattern.test(renderer))) {
+    return "macos";
+  } else if (patterns.windows.some((pattern) => pattern.test(renderer))) {
+    return "windows";
+  } else if (patterns.android.some((pattern) => pattern.test(renderer))) {
+    return "android";
+  } else if (
+    patterns.linux.some((pattern) => pattern.test(renderer)) ||
+    /NVIDIA|AMD|Intel/i.test(renderer)
+  ) {
+    return "linux";
+  } else {
+    return null;
+  }
+};
+
+export const determineDeviceType = (
+  claimedMobile: boolean | null,
+  hasTouch: boolean,
+  screenWidth: number,
+  realOs: AllowedOs | null
+): DeviceType | null => {
+  // Determine the real device type from the os
+  if (realOs === "ios" || realOs === "android") {
+    return screenWidth > 768 ? "tablet" : "mobile";
+  }
+
+  if (realOs === "windows" || realOs === "macos" || realOs === "linux") {
+    return "desktop";
+  }
+
+  // check using touch attributes if the os couldn't determine device type
+  if (hasTouch) {
+    if (screenWidth < 600) return "mobile";
+    if (screenWidth <= 1024) return "tablet";
+    if (claimedMobile === false) return "desktop"; // Likely touch laptop
+    return "tablet"; // Default large touch to tablet
+  }
+
+  if (!hasTouch) {
+    return "desktop";
+  }
+
+  return null;
+};
+
+export const guessDeviceTypeFromUA = (ua: string): DeviceType | null => {
+  const lowerUa = ua.toLowerCase();
+  if (/(tablet|ipad|playbook|silk)|(android(?!.*mobi))/i.test(lowerUa)) {
+    return "tablet";
+  }
+  if (
+    /Mobile|iP(hone|od)|Android|BlackBerry|IEMobile|Kindle|Silk-Accelerated|hpwos|Opera M(obi|ini)/i.test(
+      lowerUa
+    )
+  ) {
+    return "mobile";
+  }
+  if (
+    lowerUa.includes("windows nt") ||
+    lowerUa.includes("macintosh") ||
+    lowerUa.includes("x11")
+  ) {
+    return "desktop";
+  }
+  return null;
+};
+
+export const convertToTwoDP = (num: number): number => {
+  return parseFloat(num.toFixed(2));
+};
+
+export const isAllowedOs = (os: string): os is AllowedOs => {
+  return !!os && (ALLOWED_OS as readonly string[]).includes(os);
+};
+
+export const isAllowedDeviceType = (
+  type: DeviceType | null
+): type is DeviceType => {
+  return !!type && (ALLOWED_DEVICE_TYPES as readonly string[]).includes(type);
+};

package/src/device/modules/device/index.ts

@@ -0,0 +1,64 @@
+import {
+  RefinedDeviceResults,
+  deviceTampering,
+  DeviceResults,
+} from "../../../core";
+import { analyzeSpoofing } from "./analyze-data";
+import { getClaimedData, getSignalData } from "./gather-data";
+
+export const getDeviceDetails = async (): Promise<RefinedDeviceResults> => {
+  // 1. Initialize structure
+  const initialResults: DeviceResults = {
+    claimed: {
+      platform: "",
+      mobile: false,
+      brands: [],
+      guessedDeviceType: null,
+    },
+    signals: {
+      actualPlatform: "",
+      touchPoints: 0,
+      screen: { width: 0, height: 0, pixelRatio: 1 },
+      webGL: { vendor: undefined, renderer: undefined, error: "" },
+      userAgentString: "",
+    },
+    analysis: {
+      confidence: 1.0,
+      spoofingConfidence: 0.0,
+      isSpoofed: false,
+      detectionConflicts: [],
+      realPlatform: null,
+      realDeviceType: null,
+    },
+  };
+
+  // 2. Gather Signals (Sync first)
+  const signals = getSignalData();
+  initialResults.signals = signals;
+
+  // 3. Gather Claimed Data (Async) - Pass UA string from signals
+  const claimed = await getClaimedData(signals.userAgentString);
+  initialResults.claimed = claimed;
+
+  // 4. Analyze Data
+  const analysis = analyzeSpoofing(claimed, signals);
+  initialResults.analysis = analysis;
+
+  // 5. Format Final Output
+  const tamperingResult = (): deviceTampering => {
+    if (analysis.isSpoofed) {
+      return { status: true, confidence: analysis.spoofingConfidence };
+    } else {
+      return { status: false };
+    }
+  };
+
+  const finalResults: RefinedDeviceResults = {
+    ...initialResults,
+    deviceOs: analysis.realPlatform,
+    deviceType: analysis.realDeviceType,
+    tampering: tamperingResult(),
+  };
+
+  return finalResults;
+};