devicer.js 1.0.13 → 1.2.0

package/src/libs/registry.ts

@@ -0,0 +1,81 @@
+import type { Comparator } from "../types/data";
+import { initializeDefaultRegistry } from "./defaults";
+
+interface RegistryState {
+  comparators: Record<string, Comparator>;
+  weights: Record<string, number>;
+  defaultWeight: number;
+}
+
+let registry: RegistryState = {
+  comparators: {},
+  weights: {},
+  defaultWeight: 5,
+};
+
+let defaultsInitialized = false;
+
+/** Internal helper – called automatically on first use */
+function ensureDefaults(): void {
+  if (!defaultsInitialized) {
+    initializeDefaultRegistry();
+    defaultsInitialized = true;
+  }
+}
+
+/** Register a custom similarity comparator for a field or nested path */
+export function registerComparator(path: string, comparator: Comparator): void {
+  if (typeof comparator !== "function") {
+    throw new Error("Comparator must be a function returning a 0–1 similarity score");
+  }
+  registry.comparators[path] = comparator;
+}
+
+/** Register (or override) the weight for a field or nested path */
+export function registerWeight(path: string, weight: number): void {
+  if (typeof weight !== "number" || weight < 0) {
+    throw new Error("Weight must be a non-negative number");
+  }
+  registry.weights[path] = weight;
+}
+
+/** Convenience: register weight + comparator in one call (most common pattern) */
+export function registerPlugin(
+  path: string,
+  config: { weight?: number; comparator?: Comparator }
+): void {
+  if (config.weight !== undefined) registerWeight(path, config.weight);
+  if (config.comparator !== undefined) registerComparator(path, config.comparator);
+}
+
+/** Change the fallback weight for any unregistered field */
+export function setDefaultWeight(weight: number): void {
+  registry.defaultWeight = Math.max(0, weight);
+}
+
+/** Remove a registered comparator */
+export function unregisterComparator(path: string): boolean {
+  return delete registry.comparators[path];
+}
+
+/** Remove a registered weight */
+export function unregisterWeight(path: string): boolean {
+  return delete registry.weights[path];
+}
+
+/** Reset everything (perfect for tests) */
+export function clearRegistry(): void {
+  registry = { comparators: {}, weights: {}, defaultWeight: 5 };
+}
+
+// Internal only – used by createConfidenceCalculator
+export function getGlobalRegistry(): Readonly<RegistryState> {
+  ensureDefaults();
+  return {
+    ...registry,
+    comparators: { ...registry.comparators },
+    weights: { ...registry.weights },
+  };
+}
+
+export { initializeDefaultRegistry };

package/src/libs/tlsh.ts

@@ -1,19 +1,19 @@
-import hash from 'tlsh';
-import DigestHashBuilder from 'tlsh/lib/digests/digest-hash-builder.js';
-
-export function getHash(data: string): string {
-  // Convert the input data to a string if it's not already
-  const inputString = typeof data === 'string' ? data : JSON.stringify(data);
-  
-  // Generate the TLSH hash
-  const tlshHash = hash(inputString);
-  
-  // Return the hash as a string
-  return tlshHash;
-}
-
-export function compareHashes(hash1: string, hash2: string): number {
-  const digest1 = DigestHashBuilder().withHash(hash1).build();
-  const digest2 = DigestHashBuilder().withHash(hash2).build();
-  return digest1.calculateDifference(digest2, true);
+import hash from 'tlsh';
+import DigestHashBuilder from 'tlsh/lib/digests/digest-hash-builder.js';
+
+export function getHash(data: string): string {
+  // Convert the input data to a string if it's not already
+  const inputString = typeof data === 'string' ? data : JSON.stringify(data);
+  
+  // Generate the TLSH hash
+  const tlshHash = hash(inputString);
+  
+  // Return the hash as a string
+  return tlshHash;
+}
+
+export function compareHashes(hash1: string, hash2: string): number {
+  const digest1 = DigestHashBuilder().withHash(hash1).build();
+  const digest2 = DigestHashBuilder().withHash(hash2).build();
+  return digest1.calculateDifference(digest2, true);
 }

package/src/main.ts

@@ -1,4 +1,27 @@
-import { FPUserDataSet, FPDataSet } from "./types/data";
-import { compareArrays, compareDatasets, calculateConfidence } from "./libs/confidence";
-
-export { type FPUserDataSet, type FPDataSet, compareArrays, compareDatasets, calculateConfidence };
+import { FPUserDataSet, FPDataSet } from "./types/data";
+import { calculateConfidence, createConfidenceCalculator } from "./libs/confidence";
+import {
+    registerComparator,
+    registerWeight,
+    registerPlugin,
+    unregisterComparator,
+    unregisterWeight,
+    setDefaultWeight,
+    clearRegistry,
+    initializeDefaultRegistry
+} from "./libs/registry";
+
+export {
+    type FPUserDataSet,
+    type FPDataSet,
+    calculateConfidence,
+    createConfidenceCalculator,
+    registerComparator,
+    registerWeight,
+    registerPlugin,
+    unregisterComparator,
+    unregisterWeight,
+    setDefaultWeight,
+    clearRegistry,
+    initializeDefaultRegistry
+};

package/src/tlsh.d.ts

@@ -1,14 +1,14 @@
-declare module 'tlsh' {
-  function hash(data: string): string;
-  export default hash;
-}
-
-declare module 'tlsh/lib/digests/digest-hash-builder.js' {
-  export default function DigestHashBuilder(): {
-    withHash: (hash: string) => {
-      build: () => {
-        calculateDifference: (other: any, normalize?: boolean) => number;
-      };
-    };
-  };
+declare module 'tlsh' {
+  function hash(data: string): string;
+  export default hash;
+}
+
+declare module 'tlsh/lib/digests/digest-hash-builder.js' {
+  export default function DigestHashBuilder(): {
+    withHash: (hash: string) => {
+      build: () => {
+        calculateDifference: (other: any, normalize?: boolean) => number;
+      };
+    };
+  };
 }

package/src/types/data.ts

@@ -1,25 +1,60 @@
-export interface FPUserDataSet {
-  fonts: string[];
-  hardware: {
-    cpu: string;
-    gpu: string;
-    ram: number; // in MB
-  }
-  userAgent: string;
-  screen: {
-    width: number;
-    height: number;
-    colorDepth: number;
-  };
-  timezone: string;
-  ip: string;
-  languages: string[];
-  plugins: string[];
-  canvasHash: string;
-  audioHash: string;
-  webglHash: string;
-}
-
-export interface FPDataSet {
-  [key: string]: any;
+export interface FPUserDataSet {
+  userAgent: string;
+  platform: string;
+  timezone: string;
+  language: string;
+  languages: string[];
+  cookieEnabled: boolean;
+  doNotTrack: string | boolean;
+  hardwareConcurrency: number;
+  deviceMemory: number | string;
+  product: string;
+  productSub: string;
+  vendor: string;
+  vendorSub: string;
+  appName: string;
+  appVersion: string;
+  appCodeName: string;
+  appMinorVersion: string;
+  buildID: string;
+  plugins: {
+    name: string;
+    description: string;
+  }[];
+  mimeTypes: {
+    type: string;
+    suffixes: string;
+    description: string;
+  }[];
+  screen: {
+    width: number;
+    height: number;
+    colorDepth: number;
+    pixelDepth: number;
+    orientation: {
+      type: string;
+      angle: number;
+    };
+  };
+  fonts: string[];
+  highEntropyValues: Record<string, string | number | boolean>;
+}
+
+export type FPDataSet<T extends Record<string, any> = FPUserDataSet> = T;
+
+export type Comparator = (value1: any, value2: any, path?: string) => number; // 0.0–1.0 similarity
+
+export interface ComparisonOptions {
+  /** Field/path weights (higher = more important). Will be normalized automatically. */
+  weights?: Record<string, number>;
+  /** Custom similarity functions (your plugin system) */
+  comparators?: Record<string, Comparator>;
+  /** Fallback weight for any field without an explicit weight */
+  defaultWeight?: number;
+  /** How much weight to give the TLSH hash component (0–1) */
+  tlshWeight?: number;
+  /** Max recursion depth for nested objects/arrays */
+  maxDepth?: number;
+  /** Whether this calculator should use the global registry (default: true) */
+  useGlobalRegistry?: boolean;
 }

package/tests/confidence.test.ts

@@ -1,110 +1,163 @@
-import { it, describe, expect } from 'vitest';
-import { FPUserDataSet } from '../src/types/data';
-import { calculateConfidence } from '../src/libs/confidence';
-import { randomString } from './tlsh.test';
-
-const sampleData1: FPUserDataSet = {
-  fonts: ['Arial', 'Verdana'],
-  hardware: {
-    cpu: 'Intel Core i7',
-    gpu: 'NVIDIA GTX 1080',
-    ram: 16384 // in MB
-  },
-  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3',
-  screen: {
-    width: 1920,
-    height: 1080,
-    colorDepth: 24
-  },
-  timezone: 'America/New_York',
-  ip: '157.185.170.244',
-  languages: ['en-US', 'en'],
-  plugins: ['Chrome PDF Viewer', 'Shockwave Flash'],
-  canvasHash: randomString(524),
-  audioHash: randomString(524),
-  webglHash: randomString(524)
-};
-
-const sampleData2: FPUserDataSet = {
-  fonts: ['Arial', 'Verdana'],
-  hardware: {
-    cpu: 'Pentium 4',
-    gpu: 'Intel HD Graphics',
-    ram: 4096 // in MB
-  },
-  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3',
-  screen: {
-    width: 1280,
-    height: 720,
-    colorDepth: 24
-  },
-  timezone: 'Europe/London',
-  ip: '178.238.11.6',
-  languages: ['en-GB', 'en'],
-  plugins: ['Chrome PDF Viewer', 'Shockwave Flash'],
-  canvasHash: randomString(524),
-  audioHash: randomString(524),
-  webglHash: randomString(524)
-};
-
-describe('Confidence Calculation', () => {
-  it('should calculate confidence between two user data objects', () => {
-    const confidence = calculateConfidence(sampleData1, sampleData2);
-    console.log('Confidence:', confidence);
-    expect(typeof confidence).toBe('number');
-    expect(confidence).toBeGreaterThanOrEqual(0);
-    expect(confidence).toBeLessThanOrEqual(100);
-  });
-
-  it('should return 100% confidence for identical user data', () => {
-    const confidence = calculateConfidence(sampleData1, sampleData1);
-    expect(confidence).toBe(100);
-  });
-
-  it('should return high confidence for similar user data', () => {
-    const similarData: FPUserDataSet = {
-      ...sampleData1,
-      hardware: {
-        ...sampleData1.hardware,
-        ram: 8192 // Slightly different RAM
-      }
-    };
-    const confidence = calculateConfidence(sampleData1, similarData);
-    console.log('Confidence for similar data:', confidence);
-    expect(confidence).toBeGreaterThan(80);
-  });
-
-  it('should return lower confidence for different user data', () => {
-    const confidence = calculateConfidence(sampleData1, sampleData2);
-    console.log('Confidence for different data:', confidence);
-    expect(confidence).toBeLessThan(10);
-  });
-
-  it('should return middling confidence for partially similar data', () => {
-    const partialData: FPUserDataSet = {
-      ...sampleData1,
-      hardware: {
-        cpu: 'Pentium 4',
-        gpu: 'Intel HD Graphics',
-        ram: 4096
-      },
-      timezone: 'Europe/London',
-      ip: '178.238.11.6'
-    };
-    const confidence = calculateConfidence(sampleData1, partialData);
-    console.log('Confidence for partially similar data:', confidence);
-    expect(confidence).toBeGreaterThan(10);
-    expect(confidence).toBeLessThan(95);
-  });
-
-  it('should handle empty datasets and nonetypes gracefully', () => {
-    const incompleteData = {
-      ...sampleData1,
-      hardware: {},
-      screen: null
-    };
-    const confidence = calculateConfidence(sampleData1, incompleteData);
-    expect(confidence).toBeGreaterThan(0); // Expecting some confidence even with missing data
-    expect(confidence).toBeLessThan(100); // Not identical, so confidence should not be 100
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { calculateConfidence } from '../src/libs/confidence';
+import type { FPUserDataSet } from '../src/types/data';
+
+const sampleData1: FPUserDataSet = {
+	userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/121.0.0.0 Safari/537.36',
+	platform: 'Win32',
+	timezone: 'America/New_York',
+	language: 'en-US',
+	languages: ['en-US', 'en'],
+	cookieEnabled: true,
+	doNotTrack: '1',
+	hardwareConcurrency: 8,
+	deviceMemory: 8,
+	product: 'Gecko',
+	productSub: '20030107',
+	vendor: 'Google Inc.',
+	vendorSub: '',
+	appName: 'Netscape',
+	appVersion: '5.0 (Windows)',
+	appCodeName: 'Mozilla',
+	appMinorVersion: '0',
+	buildID: '20240101000000',
+	plugins: [
+		{ name: 'Chrome PDF Viewer', description: 'Portable Document Format' },
+		{ name: 'Widevine Content Decryption Module', description: 'Content Protection' },
+	],
+	mimeTypes: [
+		{ type: 'application/pdf', suffixes: 'pdf', description: 'Portable Document Format' },
+		{ type: 'application/json', suffixes: 'json', description: 'JSON Data' },
+	],
+	screen: {
+		width: 1920,
+		height: 1080,
+		colorDepth: 24,
+		pixelDepth: 24,
+		orientation: {
+			type: 'landscape-primary',
+			angle: 0,
+		},
+	},
+	fonts: ['Arial', 'Segoe UI', 'Times New Roman', 'Courier New'],
+	highEntropyValues: {
+		architecture: 'x86',
+		model: '',
+		platformVersion: '15.0.0',
+		uaFullVersion: '121.0.0.0',
+		wow64: false,
+	},
+};
+
+const sampleData2: FPUserDataSet = {
+	userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/122.0.0.0 Safari/537.36',
+	platform: 'Linux x86_64',
+	timezone: 'Asia/Tokyo',
+	language: 'ja-JP',
+	languages: ['ja-JP', 'ja', 'en-US'],
+	cookieEnabled: false,
+	doNotTrack: '0',
+	hardwareConcurrency: 2,
+	deviceMemory: 2,
+	product: 'Gecko',
+	productSub: '20100101',
+	vendor: 'Chromium',
+	vendorSub: 'beta',
+	appName: 'Netscape',
+	appVersion: '5.0 (X11)',
+	appCodeName: 'Mozilla',
+	appMinorVersion: '1',
+	buildID: '20240202000000',
+	plugins: [
+		{ name: 'VLC Web Plugin', description: 'VLC multimedia plugin' },
+		{ name: 'Java Plug-in', description: 'Java Runtime' },
+	],
+	mimeTypes: [
+		{ type: 'video/webm', suffixes: 'webm', description: 'WebM Video' },
+		{ type: 'application/xml', suffixes: 'xml', description: 'XML Data' },
+	],
+	screen: {
+		width: 1366,
+		height: 768,
+		colorDepth: 30,
+		pixelDepth: 30,
+		orientation: {
+			type: 'portrait-primary',
+			angle: 90,
+		},
+	},
+	fonts: ['Noto Sans JP', 'Ubuntu', 'Monospace'],
+	highEntropyValues: {
+		architecture: 'arm',
+		model: 'Chromebook',
+		platformVersion: '6.1.0',
+		uaFullVersion: '122.0.0.0',
+		wow64: true,
+	},
+};
+
+describe('Confidence Calculation', () => {
+	it('should calculate confidence between two user data objects', () => {
+		const confidence = calculateConfidence(sampleData1, sampleData2);
+		console.log('Confidence:', confidence);
+		expect(typeof confidence).toBe('number');
+		expect(confidence).toBeGreaterThanOrEqual(0);
+		expect(confidence).toBeLessThanOrEqual(100);
+	});
+
+	it('should return 100% confidence for identical user data', () => {
+		const confidence = calculateConfidence(sampleData1, sampleData1);
+		expect(confidence).toBe(100);
+	});
+
+	it('should return high confidence for similar user data', () => {
+		const similarData: FPUserDataSet = {
+			...sampleData1,
+			deviceMemory: 16,
+		};
+		const confidence = calculateConfidence(sampleData1, similarData);
+		console.log('Confidence for similar data:', confidence);
+		expect(confidence).toBeGreaterThan(80);
+	});
+
+	it('should return lower confidence for different user data', () => {
+		const confidence = calculateConfidence(sampleData1, sampleData2);
+		console.log('Confidence for different data:', confidence);
+		expect(confidence).toBeLessThan(10);
+	});
+
+	it('should return middling confidence for partially similar data', () => {
+		const partialData: FPUserDataSet = {
+			...sampleData1,
+			hardwareConcurrency: 4,
+			deviceMemory: 4,
+			timezone: 'Europe/London',
+			language: 'en-GB',
+			screen: {
+				...sampleData1.screen,
+				width: 1600,
+				height: 900,
+			},
+			highEntropyValues: {
+				...sampleData1.highEntropyValues,
+				architecture: 'arm',
+				platformVersion: '14.0.0',
+			},
+		};
+		const confidence = calculateConfidence(sampleData1, partialData);
+		console.log('Confidence for partially similar data:', confidence);
+		expect(confidence).toBeGreaterThan(10);
+		expect(confidence).toBeLessThan(95);
+	});
+
+	it('should handle empty datasets and nonetypes gracefully', () => {
+		const incompleteData = {
+			...sampleData1,
+			plugins: [],
+			screen: null,
+		} as unknown as FPUserDataSet;
+		const confidence = calculateConfidence(sampleData1, incompleteData);
+		expect(confidence).toBeGreaterThan(0);
+		expect(confidence).toBeLessThan(100);
+	});
+});