@thumbmarkjs/thumbmarkjs 0.20.6 → 1.0.0-rc.1

package/src/factory.ts

@@ -4,21 +4,53 @@
  * 
  */
 
-import { options, optionsInterface } from './fingerprint/options';
+import { optionsInterface } from './options';
+//import { getComponentPromises } from './fingerprint/tm_functions';
+
+// Import all built-in component functions
+import getAudio from "./components/audio";
+import getCanvas from "./components/canvas";
+import getFonts from "./components/fonts";
+import getHardware from "./components/hardware";
+import getLocales from "./components/locales";
+import getMath from "./components/math";
+import getPermissions from "./components/permissions";
+import getPlugins from "./components/plugins";
+import getScreen from "./components/screen";
+import getSystem from "./components/system";
+import getWebGL from "./components/webgl";
+
+/**
+ * @description key->function map of built-in components. Do not call the function here.
+ */
+export const tm_component_promises = {
+    'audio': getAudio,
+    'canvas': getCanvas,
+    'fonts': getFonts,
+    'hardware': getHardware,
+    'locales': getLocales,
+    'math': getMath,
+    'permissions': getPermissions,
+    'plugins': getPlugins,
+    'screen': getScreen,
+    'system': getSystem,
+    'webgl': getWebGL
+};
 
 // 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>;
+    (options?: optionsInterface): Promise<componentInterface | null>;
 }
 
 // components include a dictionary of name: function.
- export const components: {[name: string]: componentFunctionInterface} = {};
+// Renamed to customComponents for clarity; this is for user-registered components.
+export const customComponents: {[name: string]: componentFunctionInterface | null} = {};
 
 //In case a promise time-outs, this is what we use as the value in place
 export const timeoutInstance: componentInterface = {
@@ -30,29 +62,8 @@ export const timeoutInstance: componentInterface = {
  * in the fingerprint.
  * @param {string} name - the name identifier of the component
  * @param {componentFunctionInterface} creationFunction - the function that implements the component
- * @returns 
+ * @returns nothing
  */ 
-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 includeComponent = (name:string, creationFunction: componentFunctionInterface, options?: optionsInterface) => {
+    customComponents[name] = creationFunction;
+};

package/src/functions/filterComponents.ts

@@ -0,0 +1,42 @@
+import { componentInterface } from "../factory";
+import { optionsInterface } from "../options";
+
+// ===================== Data Filtering =====================
+
+/**
+ * Recursively filters a componentInterface object by include/exclude options.
+ *
+ * @param obj - The object to filter
+ * @param options - Filtering options
+ * @param path - Current path (for recursion)
+ * @returns Filtered object
+ */
+export function filterThumbmarkData(
+    obj: componentInterface,
+    options?: optionsInterface,
+    path: string = ""
+): componentInterface {
+    const result: componentInterface = {};
+    const excludeList = options?.exclude || [];
+    const includeList = options?.include || [];
+
+    for (const [key, value] of Object.entries(obj)) {
+        const currentPath = path + key + ".";
+
+        if (typeof value === "object" && !Array.isArray(value)) {
+            const filtered = filterThumbmarkData(value, options, currentPath);
+            if (Object.keys(filtered).length > 0) {
+                result[key] = filtered;
+            }
+        } else {
+            const isExcluded = excludeList.some(exclusion => currentPath.startsWith(exclusion));
+            const isIncluded = includeList.some(inclusion => currentPath.startsWith(inclusion));
+
+            if (!isExcluded || isIncluded) {
+                result[key] = value;
+            }
+        }
+    }
+
+    return result;
+}

package/src/functions/functions.test.ts

@@ -0,0 +1,39 @@
+import { componentInterface } from '../factory'
+import { filterThumbmarkData } from '../utils/filterComponents'
+import { defaultOptions } from '../options';
+
+const test_components: componentInterface = {
+    'one': '1',
+    'two': 2,
+    'three': {'a': true, 'b': false}
+}
+
+describe('component filtering tests', () => {
+    test("excluding top level works", () => {
+        expect(filterThumbmarkData(test_components, 
+            { ...defaultOptions, ...{ exclude: ['one']} }
+        )).toMatchObject({
+            'two': 2, 'three': {'a': true, 'b': false}
+        })
+    });
+    test("including top level works", () => {
+        expect(filterThumbmarkData(test_components, { ...defaultOptions, ...{ include: ['one', 'two']} })).toMatchObject({
+            'one': '1', 'two': 2
+        })
+    });
+    test("excluding low-level works", () => {
+        expect(filterThumbmarkData(test_components,
+            { ...defaultOptions, ...{ exclude: ['two', 'three.a']} }
+        )).toMatchObject({
+            'one': '1',
+            'three': {'b': false}
+        })
+    });
+    test("including low-level works", () => {
+        expect(filterThumbmarkData(test_components,
+            { ...defaultOptions, ...{ include: ['one', 'three.b']} })).toMatchObject({
+            'one': '1',
+            'three': {'b': false}
+        })
+    });
+});

package/src/functions/index.ts

@@ -0,0 +1,262 @@
+/**
+ * ThumbmarkJS: Main fingerprinting and API logic
+ *
+ * This module handles component collection, API calls, uniqueness scoring, and data filtering
+ * for the ThumbmarkJS browser fingerprinting library.
+ *
+ * Exports:
+ *   - getThumbmark
+ *   - getThumbmarkDataFromPromiseMap
+ *   - resolveClientComponents
+ *   - getVersion
+ *   - filterThumbmarkData
+ *
+ * Internal helpers and types are also defined here.
+ */
+
+// ===================== Imports =====================
+import { defaultOptions, optionsInterface } from "../options";
+import { 
+    timeoutInstance,
+    componentInterface,
+    tm_component_promises,
+    customComponents,
+    includeComponent as globalIncludeComponent
+} from "../factory";
+import { hash } from "../utils/hash";
+import { raceAllPerformance } from "../utils/raceAll";
+import * as packageJson from '../../package.json';
+import { filterThumbmarkData } from './filterComponents'
+
+// ===================== Types & Interfaces =====================
+
+/**
+ * Info returned from the API (IP, classification, uniqueness, etc)
+ */
+interface infoInterface {
+    ip_address?: {
+        ip_address: string,
+        ip_identifier: string,
+        autonomous_system_number: number,
+        ip_version: 'v6' | 'v4',
+    },
+    classification?: {
+        tor: boolean,
+        proxy: boolean, // i.e. vpn and 
+        datacenter: boolean,
+        danger_level: number, // 5 is highest and should be blocked. 0 is no danger.
+    },
+    uniqueness?: {
+        score: number | string
+    },
+    timed_out?: boolean; // added for timeout handling
+}
+
+/**
+ * API response structure
+ */
+interface apiResponse {
+    thumbmark?: string;
+    info?: infoInterface;
+    version?: string;
+}
+
+/**
+ * Final thumbmark response structure
+ */
+interface thumbmarkResponse {
+    components: componentInterface,
+    info: { [key: string]: any },
+    version: string,
+    thumbmark: string,
+    /**
+     * Only present if options.performance is true.
+     */
+    elapsed?: any;
+}
+
+// ===================== Version =====================
+
+/**
+ * Returns the current package version
+ */
+export function getVersion(): string {
+    return packageJson.version;
+}
+
+// ===================== API Call Logic =====================
+
+let currentApiPromise: Promise<apiResponse> | null = null;
+let apiPromiseResult: apiResponse | null = null;
+
+/**
+ * Calls the Thumbmark API with the given components, using caching and deduplication.
+ * Returns a promise for the API response or null on error.
+ */
+export const getApiPromise = (
+    options: optionsInterface,
+    components: componentInterface
+): Promise<apiResponse | null> => {
+    // 1. If a result is already cached and caching is enabled, return it.
+    if (options.cache_api_call && apiPromiseResult) {
+        return Promise.resolve(apiPromiseResult);
+    }
+
+    // 2. If a request is already in flight, return that promise to prevent duplicate calls.
+    if (currentApiPromise) {
+        return currentApiPromise;
+    }
+
+    // 3. Otherwise, initiate a new API call with timeout.
+    const endpoint = 'https://api-dev.thumbmarkjs.com/thumbmark';
+    const fetchPromise = fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'x-api-key': options.api_key!,
+            'Authorization': 'custom-authorized',
+        },
+        body: JSON.stringify({ components: components, clientHash: hash(JSON.stringify(components)) }),
+    })
+        .then(response => {
+            // Handle HTTP errors that aren't network errors
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            return response.json();
+        })
+        .then(data => {
+            apiPromiseResult = data;      // Cache the successful result
+            currentApiPromise = null;     // Clear the in-flight promise
+            return data;
+        })
+        .catch(error => {
+            console.error('Error fetching pro data', error);
+            currentApiPromise = null;     // Also clear the in-flight promise on error
+            // Return null instead of a string to prevent downstream crashes
+            return null;
+        });
+
+    // Timeout logic
+    const timeoutMs = options.timeout || 5000;
+    const timeoutPromise = new Promise<apiResponse>((resolve) => {
+        setTimeout(() => {
+            resolve({
+                thumbmark: hash(JSON.stringify(components)),
+                info: { timed_out: true },
+                version: packageJson.version,
+            });
+        }, timeoutMs);
+    });
+
+    currentApiPromise = Promise.race([fetchPromise, timeoutPromise]);
+    return currentApiPromise;
+};
+
+// ===================== Main Thumbmark Logic =====================
+
+/**
+ * Main entry point: collects all components, optionally calls API, and returns thumbmark data.
+ *
+ * @param options - Options for fingerprinting and API
+ * @returns thumbmarkResponse (elapsed is present only if options.performance is true)
+ */
+export async function getThumbmark(options?: optionsInterface): Promise<thumbmarkResponse> {
+    const _options = { ...defaultOptions, ...options };
+    // Merge built-in and user-registered components
+    const allComponents = { ...tm_component_promises, ...customComponents };
+    const { elapsed, resolvedComponents: clientComponentsResult } = await resolveClientComponents(allComponents, _options);
+
+    const apiPromise = _options.api_key ? getApiPromise(_options, clientComponentsResult) : null;
+    const apiResult = apiPromise ? await apiPromise : null;
+
+    // Only add 'elapsed' if performance is true
+    const maybeElapsed = _options.performance ? { elapsed } : {};
+
+    if (apiResult) {
+        const info: infoInterface = apiResult.info || {};
+        return {
+            components: clientComponentsResult,
+            info,
+            version: getVersion(),
+            thumbmark: apiResult.thumbmark || 'undefined',
+            ...maybeElapsed,
+        };
+    }
+    return {
+        thumbmark: hash(JSON.stringify(clientComponentsResult)),
+        components: clientComponentsResult,
+        info: {
+            uniqueness: 'api only'
+        },
+        version: getVersion(),
+        ...maybeElapsed,
+    };
+}
+
+// ===================== Component Resolution & Performance =====================
+
+/**
+ * Resolves and times all filtered component promises from a component function map.
+ *
+ * @param comps - Map of component functions
+ * @param options - Options for filtering and timing
+ * @returns Object with elapsed times and filtered resolved components
+ */
+export async function resolveClientComponents(
+  comps: { [key: string]: (options?: optionsInterface) => Promise<componentInterface | null> },
+  options?: optionsInterface
+): Promise<{ elapsed: Record<string, number>, resolvedComponents: componentInterface }> {
+  const opts = { ...defaultOptions, ...options };
+  const filtered = Object.entries(comps)
+    .filter(([key]) => !opts?.exclude?.includes(key))
+    .filter(([key]) =>
+      opts?.include?.some(e => e.includes('.'))
+        ? opts?.include?.some(e => e.startsWith(key))
+        : opts?.include?.length === 0 || opts?.include?.includes(key)
+    );
+  const keys = filtered.map(([key]) => key);
+  const promises = filtered.map(([_, fn]) => fn(options));
+  const resolvedValues = await raceAllPerformance(promises, opts?.timeout || 5000, timeoutInstance);
+
+  const elapsed: Record<string, number> = {};
+  const resolvedComponentsRaw: Record<string, componentInterface> = {};
+
+  resolvedValues.forEach((value, index) => {
+    if (value.value != null) {
+      resolvedComponentsRaw[keys[index]] = value.value;
+      elapsed[keys[index]] = value.elapsed ?? 0;
+    }
+  });
+
+  const resolvedComponents = filterThumbmarkData(resolvedComponentsRaw, opts, "");
+  return { elapsed, resolvedComponents };
+}
+
+// ===================== Logging (Internal) =====================
+
+/**
+ * Logs thumbmark data to remote logging endpoint (only once per session)
+ * @internal
+ */
+async function logThumbmarkData(thisHash: string, thumbmarkData: componentInterface) {
+    const url = 'https://logging.thumbmarkjs.com/v1/log';
+    const payload = {
+        thumbmark: thisHash,
+        components: thumbmarkData,
+        version: getVersion()
+    };
+    if (!sessionStorage.getItem("_tmjs_l")) {
+        sessionStorage.setItem("_tmjs_l", "1");
+        try {
+            await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(payload)
+            });
+        } catch { /* do nothing */ }
+    }
+}
+
+export { globalIncludeComponent as includeComponent };

package/src/functions/legacy_functions.ts

@@ -0,0 +1,54 @@
+/**
+ * This file is here to support legacy implementations.
+ * Eventually, these functions will be removed to keep the library small.
+ */
+
+import { componentInterface } from '../factory'
+import { options} from '../options'
+import { resolveClientComponents, getThumbmark } from '.';
+import { tm_component_promises } from "../factory";
+
+/**
+ * 
+ * @deprecated
+ */
+export async function getFingerprintData() {
+    const thumbmarkData = await getThumbmark(options);
+    return thumbmarkData.components;
+}
+
+/**
+ * 
+ * @param includeData boolean
+ * @deprecated this function is going to be removed. use getThumbmark or Thumbmark class instead.
+ */
+export async function getFingerprint(includeData?: false): Promise<string>
+export async function getFingerprint(includeData: true): Promise<{ hash: string, data: componentInterface }>
+export async function getFingerprint(includeData?: boolean): Promise<string | { hash: string, data: componentInterface }> {
+    try {
+        const thumbmarkData = await getThumbmark(options);
+        if (includeData) {
+            return { hash: thumbmarkData.thumbmark.toString(), data: thumbmarkData.components}
+        } else {
+            return thumbmarkData.thumbmark.toString()
+        }
+    } catch (error) {
+        throw error
+    }
+}
+/**
+ * 
+ * @deprecated use Thumbmark or getThumbmark instead with options
+ */
+export async function getFingerprintPerformance() {
+    try {
+        const { elapsed, resolvedComponents } = await resolveClientComponents(tm_component_promises, options);
+        // Legacy format: merge resolvedComponents and elapsed into one object
+        return {
+            ...resolvedComponents,
+            elapsed
+        };
+    } catch (error) {
+        throw error;
+    }
+}

package/src/index.ts

@@ -1,6 +1,15 @@
-import { getFingerprint, getFingerprintData, getFingerprintPerformance, getVersion } from './fingerprint/functions'
-import { setOption } from './fingerprint/options'
+import {
+    getFingerprint,
+    getFingerprintData,
+    getFingerprintPerformance
+ } from './functions/legacy_functions'
+import { getThumbmark, getVersion } from './functions'
+import { setOption } from './options'
 import { includeComponent } from './factory'
-import './components'
+import { Thumbmark } from './thumbmark'
 
-export { setOption, getVersion, getFingerprint, getFingerprintData, getFingerprintPerformance, includeComponent }
+export { Thumbmark, getThumbmark, getVersion,
+
+    // deprecated functions. Don't use anymore.
+    setOption, getFingerprint, getFingerprintData, getFingerprintPerformance, includeComponent
+}

package/src/{fingerprint/options.ts → options.ts}

@@ -1,23 +1,31 @@
 export interface optionsInterface {
-    exclude: string[],
-    include: string[],
-    webgl_runs?: number,
-    canvas_runs?: number,
-    permissions_to_check?: PermissionName[], // new option
-    retries?: number, // new option
-    timeout: number, // new option
-    logging: boolean
+    exclude?: string[],
+    include?: string[],
+    permissions_to_check?: PermissionName[],
+    timeout?: number,
+    logging?: boolean,
+    api_key?: string,
+    cache_api_call?: boolean,
+    performance?: boolean, // re-added
 }
 
-export let options: optionsInterface = {
+export const defaultOptions: optionsInterface = {
     exclude: [],
     include: [],
     logging: true,
-    timeout: 1000
-}
+    timeout: 5000,
+    cache_api_call: true,
+    performance: false // re-added
+    };
 
+export let options = {...defaultOptions};
+/**
+ * 
+ * @param key @deprecated this function will be removed
+ * @param value 
+ */
 export function setOption<K extends keyof optionsInterface>(key: K, value: optionsInterface[K]) {
-    if (!['include', 'exclude', 'permissions_to_check', 'retries', 'timeout', 'logging'].includes(key))
+    if (!['include', 'exclude', 'permissions_to_check', 'retries', 'timeout', 'logging', 'api_key', 'cache_api_call'].includes(key))
         throw new Error('Unknown option ' + key)
     if (['include', 'exclude', 'permissions_to_check'].includes(key) && !(Array.isArray(value) && value.every(item => typeof item === 'string')) )
         throw new Error('The value of the include, exclude and permissions_to_check must be an array of strings');

package/src/thumbmark.ts

@@ -0,0 +1,41 @@
+import { optionsInterface } from "./options";
+import { getThumbmark, getVersion, includeComponent as globalIncludeComponent } from './functions';
+import { defaultOptions } from "./options";
+import { componentInterface } from "./factory";
+
+/**
+ * A client for generating thumbmarks with a persistent configuration.
+ */
+    
+export class Thumbmark {
+    private options: optionsInterface;
+  
+    /**
+     * Creates a new Thumbmarker client instance.
+     * @param options - Default configuration options for this instance.
+     */
+    constructor(options?: optionsInterface) {
+      this.options = { ...defaultOptions, ...options };
+    }
+  
+    /**
+     * Generates a thumbmark using the instance's configuration.
+     * @param overrideOptions - Options to override for this specific call.
+     * @returns The thumbmark result.
+     */
+    public async get(overrideOptions?: optionsInterface): Promise<any> {
+      const finalOptions = { ...this.options, ...overrideOptions };
+      return getThumbmark(finalOptions);
+    }
+    public getVersion(): string {
+      return getVersion()
+    }
+    /**
+     * Register a custom component to be included in the fingerprint.
+     * @param key - The component name
+     * @param fn - The component function
+     */
+    public includeComponent(key: string, fn: (options?: optionsInterface) => Promise<componentInterface | null>) {
+      globalIncludeComponent(key, fn);
+    }
+}

package/src/{declarations.d.ts → types/global.d.ts}

@@ -5,8 +5,8 @@ interface ApplePaySession {
 }
 
 interface Window {
-    webkitAudioContext: typeof AudioContext
     webkitOfflineAudioContext: typeof OfflineAudioContext
+    webkitAudioContext: typeof AudioContext
     ApplePaySession: typeof ApplePaySession
   }
 

package/src/utils/raceAll.ts

@@ -1,5 +1,3 @@
-import { componentInterface } from '../factory'
-
 type DelayedPromise<T> = Promise<T>;
 
 export function delay<T>(t: number, val: T): DelayedPromise<T> {

package/src/components/index.ts

@@ -1,17 +0,0 @@
-/**
- * Does anyone have a cleaner way of doing this?
- * I want to import all the components in this folder
- * Feels a little dumb I'm doing this manually.
- */
-
-import './audio/audio'
-import './canvas/canvas'
-import './fonts/fonts'
-import './hardware/hardware'
-import './locales/locales'
-import './permissions/permissions'
-import './plugins/plugins'
-import './screen/screen'
-import './system/system'
-import './webgl/webgl'
-import './math/math'

package/src/components/math/math.ts

@@ -1,39 +0,0 @@
-import { componentInterface, includeComponent } from '../../factory'
-
-const getMathInfo = async (): Promise<componentInterface> => {
-    return {
-        acos: Math.acos(0.5),
-        asin: integrate(Math.asin, -1, 1, 97),
-        atan: integrate(Math.atan, -1, 1, 97),
-        cos: integrate(Math.cos, 0, Math.PI, 97),
-        cosh: Math.cosh(9/7),
-        e: Math.E,
-        largeCos: Math.cos(1e20),
-        largeSin: Math.sin(1e20),
-        largeTan: Math.tan(1e20),
-        log: Math.log(1000),
-        pi: Math.PI,
-        sin: integrate(Math.sin, -Math.PI, Math.PI, 97),
-        sinh: integrate(Math.sinh, -9/7, 7/9, 97),
-        sqrt: Math.sqrt(2),
-        tan: integrate(Math.tan, 0, 2 * Math.PI, 97),
-        tanh: integrate(Math.tanh, -9/7, 7/9, 97),
-    }
-}
-
-/** This might be a little excessive, but I wasn't sure what number to pick for some of the
- * trigonometric functions. Using an integral here, so a few numbers are calculated. However,
- * I do this mainly for those integrals that sum up to a small value, otherwise there's no point.
-*/ 
-
-const integrate = (f: (x: number) => number, a: number, b: number, n: number): number => {
-    const h = (b - a) / n;
-    let sum = 0;
-    for (let i = 0; i < n; i++) {
-        const x = a + (i + 0.5) * h;
-        sum += f(x);
-    }
-    return sum * h;
-};
-
-includeComponent('math', getMathInfo);