fpscanner 0.2.0 → 0.9.2

package/package.json

@@ -1,16 +1,55 @@
 {
   "name": "fpscanner",
-  "version": "0.2.0",
-  "description": "Detect bots using fingerprinting",
-  "main": "src/fpScanner.js",
+  "version": "0.9.2",
+  "description": "A lightweight browser fingerprinting and bot detection library with encryption, obfuscation, and cross-context validation",
+  "main": "dist/fpScanner.cjs.js",
+  "module": "dist/fpScanner.es.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "fpscanner": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "scripts"
+  ],
   "scripts": {
-    "test": "./node_modules/.bin/mocha --recursive test"
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "build:vite": "vite build",
+    "build:dev": "node bin/cli.js build --key=dev-key --no-obfuscate",
+    "build:prod": "node bin/cli.js build",
+    "build:prod:plain": "node bin/cli.js build --no-obfuscate",
+    "build:obfuscate": "node bin/cli.js build --key=dev-key",
+    "watch": "concurrently \"FP_ENCRYPTION_KEY=dev-key vite build --watch\" \"tsc --watch --emitDeclarationOnly\"",
+    "dev": "vite",
+    "dev:build": "npm run build:dev && vite",
+    "dev:obfuscate": "npm run build:obfuscate && vite",
+    "test": "npm run test:playwright",
+    "test:vitest": "vitest",
+    "test:playwright": "npm run build:obfuscate && npx playwright test",
+    "test:playwright:headed": "npm run build:obfuscate && npx playwright test --headed"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/antoinevastel/fpscanner.git"
+    "url": "git+https://github.com/antoinevastel/fpscanner.git"
   },
-  "keywords": [],
+  "keywords": [
+    "fingerprinting",
+    "browser-fingerprint",
+    "bot-detection",
+    "automation-detection",
+    "fraud-detection",
+    "selenium",
+    "puppeteer",
+    "playwright",
+    "webdriver",
+    "headless",
+    "anti-bot",
+    "device-fingerprint",
+    "browser-detection",
+    "security"
+  ],
   "author": "antoinevastel <antoine.vastel@gmail.com>",
   "license": "MIT",
   "bugs": {
@@ -18,16 +57,20 @@
   },
   "homepage": "https://github.com/antoinevastel/fpscanner",
   "dependencies": {
-    "ua-parser-js": "^0.7.17"
+    "ua-parser-js": "^0.7.18",
+    "javascript-obfuscator": "^5.1.0",
+    "terser": "^5.46.0"
   },
   "devDependencies": {
-    "chai": "^4.1.2",
-    "fpcollect": "^0.5.0",
-    "karma": "^2.0.0",
-    "karma-chai": "^0.1.0",
-    "karma-chrome-launcher": "^2.2.0",
-    "karma-mocha": "^1.3.0",
-    "mocha": "^5.0.4",
-    "puppeteer": "^1.1.1"
+    "@playwright/test": "^1.57.0",
+    "@vitest/ui": "^4.0.16",
+    "chai": "^4.2.0",
+    "concurrently": "^9.2.1",
+    "fpcollect": "^1.0.4",
+    "mocha": "^5.2.0",
+    "puppeteer": "^1.9.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
   }
 }

package/scripts/build-custom.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Build fpscanner with a custom encryption key and optional obfuscation.
+ * This script:
+ * 1. Runs Vite build with the key injected via environment variable
+ * 2. Generates TypeScript declarations
+ * 3. Optionally obfuscates the output
+ * 4. Minifies with Terser (when obfuscating)
+ * 5. Removes source maps (when obfuscating)
+ */
+module.exports = async function build(args) {
+  // Parse arguments
+  const keyArg = args.find(a => a.startsWith('--key='));
+  const packageDirArg = args.find(a => a.startsWith('--package-dir='));
+  const skipObfuscation = args.includes('--no-obfuscate');
+  
+  if (!keyArg) {
+    throw new Error('Missing --key argument');
+  }
+  
+  const key = keyArg.split('=').slice(1).join('=');
+  const packageDir = packageDirArg 
+    ? packageDirArg.split('=')[1] 
+    : path.dirname(__dirname);
+  
+  const distDir = path.join(packageDir, 'dist');
+  const files = ['fpScanner.es.js', 'fpScanner.cjs.js'];
+  const sentinel = '__DEFAULT_FPSCANNER_KEY__';
+  
+  console.log('');
+  console.log('🔨 Building fpscanner with custom key...');
+  console.log(`   Package: ${packageDir}`);
+  console.log(`   Output:  ${distDir}`);
+  console.log(`   Obfuscation: ${skipObfuscation ? 'disabled' : 'enabled'}`);
+  console.log('');
+  
+  // Check if dist files exist (consumer mode vs development mode)
+  const distExists = fs.existsSync(distDir) && 
+                     files.some(file => fs.existsSync(path.join(distDir, file)));
+  
+  if (!distExists) {
+    // Development mode: build from source first
+    console.log('📦 Step 0/5: Dist files not found, building from source...');
+    try {
+      execSync('npm run build:vite', {
+        cwd: packageDir,
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          FP_ENCRYPTION_KEY: key,
+        },
+      });
+      console.log('');
+      console.log('📝 Generating TypeScript declarations...');
+      execSync('npx tsc --emitDeclarationOnly', {
+        cwd: packageDir,
+        stdio: 'inherit',
+      });
+    } catch (err) {
+      throw new Error('Build from source failed');
+    }
+    console.log('');
+  }
+  
+  // Step 1: Inject encryption key into pre-built dist files
+  console.log('📦 Step 1/5: Injecting encryption key...');
+  
+  let keyInjected = false;
+  for (const file of files) {
+    const filePath = path.join(distDir, file);
+    
+    if (!fs.existsSync(filePath)) {
+      console.log(`   ⚠️  ${file} not found, skipping`);
+      continue;
+    }
+    
+    let code = fs.readFileSync(filePath, 'utf8');
+    
+    // Check if sentinel exists
+    if (!code.includes(sentinel)) {
+      console.log(`   ⚠️  ${file} does not contain the default key sentinel, skipping`);
+      continue;
+    }
+    
+    // Replace all occurrences of the sentinel with the actual key
+    const escapedSentinel = sentinel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    code = code.replace(new RegExp(`"${escapedSentinel}"`, 'g'), JSON.stringify(key));
+    
+    fs.writeFileSync(filePath, code);
+    keyInjected = true;
+    console.log(`   ✓ ${file}`);
+  }
+  
+  if (!keyInjected) {
+    console.log('   ℹ️  Key already injected during build step');
+  }
+  
+  // Step 2: Skip TypeScript declarations (already generated)
+  console.log('');
+  console.log('⏭️  Step 2/5: TypeScript declarations already present, skipping...');
+  
+  // Step 3: Obfuscate (optional)
+  if (!skipObfuscation) {
+    console.log('');
+    console.log('🔒 Step 3/5: Obfuscating output...');
+    
+    let JavaScriptObfuscator;
+    try {
+      JavaScriptObfuscator = require('javascript-obfuscator');
+    } catch (err) {
+      console.log('   ⚠️  javascript-obfuscator not installed, skipping obfuscation');
+      console.log('   To enable obfuscation, run: npm install --save-dev javascript-obfuscator');
+      skipObfuscation = true;
+    }
+    
+    if (JavaScriptObfuscator) {
+      const files = ['fpScanner.es.js', 'fpScanner.cjs.js'];
+      
+      for (const file of files) {
+        const filePath = path.join(distDir, file);
+        
+        if (!fs.existsSync(filePath)) {
+          console.log(`   ⚠️  ${file} not found, skipping`);
+          continue;
+        }
+        
+        const code = fs.readFileSync(filePath, 'utf8');
+        
+        const obfuscated = JavaScriptObfuscator.obfuscate(code, {
+          compact: true,
+          controlFlowFlattening: true,
+          controlFlowFlatteningThreshold: 0.4,
+          deadCodeInjection: true,
+          deadCodeInjectionThreshold: 0.1,
+          stringArray: true,
+          stringArrayThreshold: 0.95,
+          stringArrayEncoding: ['rc4'],
+          transformObjectKeys: true,
+          unicodeEscapeSequence: false,
+          // Preserve functionality
+          selfDefending: false,
+          disableConsoleOutput: false,
+        });
+        
+        fs.writeFileSync(filePath, obfuscated.getObfuscatedCode());
+        console.log(`   ✓ ${file}`);
+      }
+      
+      // Step 4: Minify with Terser
+      console.log('');
+      console.log('📦 Step 4/5: Minifying with Terser...');
+      
+      let terser;
+      try {
+        terser = require('terser');
+      } catch (err) {
+        console.log('   ⚠️  terser not installed, skipping minification');
+        console.log('   To enable minification, run: npm install --save-dev terser');
+      }
+      
+      if (terser) {
+        for (const file of files) {
+          const filePath = path.join(distDir, file);
+          
+          if (!fs.existsSync(filePath)) {
+            continue;
+          }
+          
+          const code = fs.readFileSync(filePath, 'utf8');
+          const minified = await terser.minify(code, {
+            compress: {
+              drop_console: false,
+              dead_code: true,
+              unused: true,
+            },
+            mangle: {
+              toplevel: true,
+            },
+            format: {
+              comments: false,
+            },
+          });
+          
+          if (minified.error) {
+            console.log(`   ⚠️  Failed to minify ${file}: ${minified.error}`);
+          } else {
+            fs.writeFileSync(filePath, minified.code);
+            console.log(`   ✓ ${file}`);
+          }
+        }
+      }
+      
+      // Step 5: Delete all source map files so DevTools can't show original source
+      console.log('');
+      console.log('🗑️  Step 5/5: Removing source maps...');
+      
+      function deleteMapFiles(dir, prefix = '') {
+        if (!fs.existsSync(dir)) {
+          return;
+        }
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+          const fullPath = path.join(dir, file);
+          const stat = fs.statSync(fullPath);
+          
+          if (stat.isDirectory()) {
+            deleteMapFiles(fullPath, prefix + file + '/');
+          } else if (file.endsWith('.map')) {
+            fs.unlinkSync(fullPath);
+            console.log(`   ✓ Deleted ${prefix}${file}`);
+          }
+        }
+      }
+      
+      deleteMapFiles(distDir);
+    }
+  } else {
+    console.log('');
+    console.log('⏭️  Steps 3-5/5: Skipping obfuscation, minification, and source map removal (--no-obfuscate)');
+  }
+  
+  console.log('');
+  console.log('✅ Build complete!');
+  console.log('');
+  console.log('   Your custom fpscanner build is ready in:');
+  console.log(`   ${distDir}`);
+  console.log('');
+  console.log('   Import it in your code:');
+  console.log("   import FingerprintScanner from 'fpscanner';");
+  console.log('');
+};
+
+// Allow running directly
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  module.exports(args)
+    .catch((err) => {
+      console.error('❌ Build failed:', err.message);
+      process.exit(1);
+    });
+}

package/src/crypto-helpers.ts

@@ -0,0 +1,50 @@
+/**
+ * Simple and fast XOR-based encryption/decryption
+ * Note: This is NOT cryptographically secure - use only for obfuscation
+ */
+
+/**
+ * Encrypts a string using XOR cipher with the provided key
+ * @param plaintext - The string to encrypt
+ * @param key - The encryption key as a string
+ * @returns Encrypted string (base64 encoded)
+ */
+export async function encryptString(plaintext: string, key: string): Promise<string> {
+    const keyBytes = new TextEncoder().encode(key);
+    const textBytes = new TextEncoder().encode(plaintext);
+    const encrypted = new Uint8Array(textBytes.length);
+
+    for (let i = 0; i < textBytes.length; i++) {
+        encrypted[i] = textBytes[i] ^ keyBytes[i % keyBytes.length];
+    }
+
+    // Convert to base64 for safe string representation
+    const binaryString = String.fromCharCode(...encrypted);
+    return btoa(binaryString);
+}
+
+/**
+ * Decrypts a string that was encrypted with encryptString
+ * @param ciphertext - The encrypted string (base64 encoded)
+ * @param key - The decryption key as a string (must match encryption key)
+ * @returns Decrypted string
+ */
+export async function decryptString(ciphertext: string, key: string): Promise<string> {
+    // Decode from base64
+    const binaryString = atob(ciphertext);
+    const encrypted = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        encrypted[i] = binaryString.charCodeAt(i);
+    }
+
+    const keyBytes = new TextEncoder().encode(key);
+    const decrypted = new Uint8Array(encrypted.length);
+
+    // XOR is symmetric, so decryption is the same as encryption
+    for (let i = 0; i < encrypted.length; i++) {
+        decrypted[i] = encrypted[i] ^ keyBytes[i % keyBytes.length];
+    }
+
+    return new TextDecoder().decode(decrypted);
+}
+

package/src/detections/hasCDP.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasCDP(fingerprint: Fingerprint) {
+    return fingerprint.signals.automation.cdp === true;
+}

package/src/detections/hasContextMismatch.ts

@@ -0,0 +1,19 @@
+import { Fingerprint } from "../types";
+
+// Not used as a detection rule since, more like an indicator
+export function hasContextMismatch(fingerprint: Fingerprint, context: 'iframe' | 'worker'): boolean {
+    const s = fingerprint.signals;
+    if (context === 'iframe') {
+        return s.contexts.iframe.webdriver !== s.automation.webdriver ||
+               s.contexts.iframe.userAgent !== s.browser.userAgent ||
+               s.contexts.iframe.platform !== s.device.platform ||
+               s.contexts.iframe.memory !== s.device.memory ||
+               s.contexts.iframe.cpuCount !== s.device.cpuCount;
+    } else {
+        return s.contexts.webWorker.webdriver !== s.automation.webdriver ||
+               s.contexts.webWorker.userAgent !== s.browser.userAgent ||
+               s.contexts.webWorker.platform !== s.device.platform ||
+               s.contexts.webWorker.memory !== s.device.memory ||
+               s.contexts.webWorker.cpuCount !== s.device.cpuCount;
+    }
+}

package/src/detections/hasHeadlessChromeScreenResolution.ts

@@ -0,0 +1,10 @@
+import { Fingerprint } from '../types';
+
+export function hasHeadlessChromeScreenResolution(fingerprint: Fingerprint) {
+    const screen = fingerprint.signals.device.screenResolution;
+    if (typeof screen.width !== 'number' || typeof screen.height !== 'number') {
+        return false;
+    }
+
+    return (screen.width === 600 && screen.height === 800) || (screen.availableWidth === 600 && screen.availableHeight === 800) || (screen.innerWidth === 600 && screen.innerHeight === 800);
+}

package/src/detections/hasHighCPUCount.ts

@@ -0,0 +1,9 @@
+import { Fingerprint } from "../types";
+
+export function hasHighCPUCount(fingerprint: Fingerprint) {
+    if (typeof fingerprint.signals.device.cpuCount !== 'number') {
+        return false;
+    }
+
+    return fingerprint.signals.device.cpuCount > 70;
+}

package/src/detections/hasImpossibleDeviceMemory.ts

@@ -0,0 +1,9 @@
+import { Fingerprint } from "../types";
+
+export function hasImpossibleDeviceMemory(fingerprint: Fingerprint) {
+    if (typeof fingerprint.signals.device.memory !== 'number') {
+        return false;
+    }
+
+    return (fingerprint.signals.device.memory > 8 || fingerprint.signals.device.memory < 0.25);
+}

package/src/detections/hasMismatchPlatformIframe.ts

@@ -0,0 +1,10 @@
+import { Fingerprint } from "../types";
+import { ERROR, NA } from "../signals/utils";
+
+export function hasMismatchPlatformIframe(fingerprint: Fingerprint) {
+    if (fingerprint.signals.contexts.iframe.platform === NA || fingerprint.signals.contexts.iframe.platform === ERROR) {
+        return false;
+    }
+
+    return fingerprint.signals.device.platform !== fingerprint.signals.contexts.iframe.platform;
+}

package/src/detections/hasMismatchPlatformWorker.ts

@@ -0,0 +1,10 @@
+import { Fingerprint } from "../types";
+import { ERROR, NA, SKIPPED } from "../signals/utils";
+
+export function hasMismatchPlatformWorker(fingerprint: Fingerprint) {
+    if (fingerprint.signals.contexts.webWorker.platform === NA || fingerprint.signals.contexts.webWorker.platform === ERROR || fingerprint.signals.contexts.webWorker.platform === SKIPPED) {
+        return false;
+    }
+
+    return fingerprint.signals.device.platform !== fingerprint.signals.contexts.webWorker.platform;
+}

package/src/detections/hasMismatchWebGLInWorker.ts

@@ -0,0 +1,13 @@
+import { Fingerprint } from "../types";
+import { ERROR, NA, SKIPPED } from "../signals/utils";
+
+export function hasMismatchWebGLInWorker(fingerprint: Fingerprint) {
+    const worker = fingerprint.signals.contexts.webWorker;
+    const webGL = fingerprint.signals.graphics.webGL;
+    
+    if (worker.vendor === ERROR || worker.renderer === ERROR || webGL.vendor === NA || webGL.renderer === NA || worker.vendor === SKIPPED) {
+        return false;
+    }
+
+    return worker.vendor !== webGL.vendor || worker.renderer !== webGL.renderer;
+}

package/src/detections/hasMissingChromeObject.ts

@@ -0,0 +1,6 @@
+import { Fingerprint } from "../types";
+
+export function hasMissingChromeObject(fingerprint: Fingerprint) {
+    const userAgent = fingerprint.signals.browser.userAgent;
+    return fingerprint.signals.browser.features.chrome === false && typeof userAgent === 'string' && userAgent.includes('Chrome');
+}

package/src/detections/hasPlaywright.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasPlaywright(fingerprint: Fingerprint) {
+    return fingerprint.signals.automation.playwright === true;
+}

package/src/detections/hasSeleniumProperty.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasSeleniumProperty(fingerprint: Fingerprint) {
+    return !!fingerprint.signals.automation.selenium;
+}

package/src/detections/hasSwiftshaderRenderer.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasSwiftshaderRenderer(fingerprint: Fingerprint) {
+    return fingerprint.signals.graphics.webGL.renderer.includes('SwiftShader');
+}

package/src/detections/hasUTCTimezone.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasUTCTimezone(fingerprint: Fingerprint) {
+    return fingerprint.signals.locale.internationalization.timezone === 'UTC';
+}

package/src/detections/hasWebdriver.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasWebdriver(fingerprint: Fingerprint) {
+    return fingerprint.signals.automation.webdriver === true;
+}

package/src/detections/hasWebdriverIframe.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasWebdriverIframe(fingerprint: Fingerprint) {
+    return fingerprint.signals.contexts.iframe.webdriver === true;
+}

package/src/detections/hasWebdriverWorker.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasWebdriverWorker(fingerprint: Fingerprint) {
+    return fingerprint.signals.contexts.webWorker.webdriver === true;
+}

package/src/detections/hasWebdriverWritable.ts

@@ -0,0 +1,5 @@
+import { Fingerprint } from "../types";
+
+export function hasWebdriverWritable(fingerprint: Fingerprint) {
+    return fingerprint.signals.automation.webdriverWritable === true;
+}

package/src/globals.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build-time constant injected via Vite's define option.
+ * This is replaced with the actual encryption key during the build process.
+ * 
+ * Customers provide their key via:
+ *   - npx fpscanner build --key=their-key
+ *   - FINGERPRINT_KEY environment variable
+ *   - .env file with FINGERPRINT_KEY=their-key
+ */
+declare const __FP_ENCRYPTION_KEY__: string;