FingerprinterJS v2.0

🔐 Enterprise-grade browser fingerprinting with 19 collectors, advanced bot detection, and stable hashing.

Live Demo • NPM Package

✨ Features

• 19 Collectors - Comprehensive browser data collection
• Stable Hashing - Only stable data contributes to fingerprint hash
• Bot Detection - Detects Puppeteer, Playwright, Selenium, headless browsers
• TypeScript - Full type safety
• Zero Dependencies - Lightweight (~15KB gzipped)
• Parallel Collection - Fast data gathering

📦 Installation

npm install fingerprinter-js

🚀 Quick Start

import { Fingerprint } from "fingerprinter-js";

const result = await Fingerprint.generate({
  includeSuspectAnalysis: true
});

console.log(result.fingerprint);  // "a1b2c3d4..."
console.log(result.confidence);   // 100
console.log(result.entropy);      // 85
console.log(result.suspectAnalysis?.riskLevel); // "LOW"

📊 Result Structure

interface FingerprintResult {
  fingerprint: string;        // SHA-256 hash (stable collectors only)
  components: Record<string, unknown>; // All collected data
  confidence: number;         // 0-100%
  entropy: number;            // Bits of entropy
  duration: number;           // Generation time (ms)
  version: string;            // "2.0.0"
  suspectAnalysis?: {
    score: number;            // 0-100 (higher = more suspicious)
    riskLevel: "LOW" | "MEDIUM" | "HIGH";
    signals: SuspectSignal[];
  };
}

🎯 Collectors

Stable Collectors (included in hash)

| Collector | Description | Entropy | |-----------|-------------|---------| | userAgent | Browser User-Agent | ~8 bits | | language | Preferred languages | ~3 bits | | timezone | Timezone offset & name | ~4 bits | | screen | Resolution, color depth | ~6 bits | | plugins | Installed plugins | ~5 bits | | canvas | 2D canvas fingerprint | ~10 bits | | webgl | GPU vendor & renderer | ~9 bits | | fonts | Available system fonts | ~8 bits | | hardware | CPU cores, memory, platform | ~5 bits | | clientHints | UA Client Hints API | ~7 bits | | storage | Storage API availability | ~4 bits | | touch | Touch capabilities | ~4 bits | | math | Math precision values | ~2 bits | | mediaDevices | Cameras/mics count | ~5 bits |

Unstable Collectors (data collected but NOT in hash)

| Collector | Description | Why Unstable | |-----------|-------------|--------------| | webrtc | Local IPs, SDP | IPs can change | | battery | Battery level & charging | Values fluctuate | | connection | Network type & speed | Variables change | | permissions | Permission states | User can change | | audio | Audio processing fingerprint | Varies on first run |

⚠️ Unstable collectors provide useful data for analysis but don't affect the fingerprint hash, ensuring consistent identification.

🛡️ Bot Detection

const result = await Fingerprint.generate({
  includeSuspectAnalysis: true
});

if (result.suspectAnalysis?.riskLevel === "HIGH") {
  console.log("Bot detected:", result.suspectAnalysis.signals);
}

Detection Capabilities

• Automation Tools: Puppeteer, Playwright, Selenium, PhantomJS
• Headless Browsers: HeadlessChrome, CDP artifacts
• Inconsistencies: UA/platform mismatch, hardware anomalies
• Privacy Tools: Canvas noise, property tampering
• Known Bots: Googlebot, Bingbot, crawlers

🔧 Configuration Options

const result = await Fingerprint.generate({
  // Exclude specific collectors
  excludeCanvas: false,
  excludeWebGL: false,
  excludeAudio: false,
  excludeFonts: false,
  excludeWebRTC: false,
  excludeHardware: false,
  excludeClientHints: false,
  excludeStorage: false,
  excludeBattery: false,
  excludeConnection: false,
  excludeTouch: false,
  excludePermissions: false,
  excludeMath: false,
  excludeMediaDevices: false,
  
  // Bot detection
  includeSuspectAnalysis: true,
  
  // Custom data (optional)
  customData: {
    userId: "12345"
  },
  
  // Allow unstable custom data
  allowUnstableData: false,
  
  // Timeout per collector (ms)
  timeout: 5000
});

📱 Browser Support

| Browser | Version | |---------|---------| | Chrome | 60+ | | Firefox | 55+ | | Safari | 12+ | | Edge | 79+ |

⚠️ This library is browser-only. Node.js is not supported.

🔄 Stability Guarantee

The fingerprint hash is stable across page reloads because:

1. Only stable collectors contribute to the hash
2. Temporal values (timestamps, UUIDs) are automatically filtered from custom data
3. Unstable platform data (battery level, network speed) is collected but excluded from hash

// This will produce the same hash every time
const result1 = await Fingerprint.generate();
const result2 = await Fingerprint.generate();
console.log(result1.fingerprint === result2.fingerprint); // true

🧩 Individual Collectors

import { 
  CanvasCollector, 
  WebGLCollector,
  FontsCollector 
} from "fingerprinter-js";

// Use collectors individually
const canvas = new CanvasCollector();
const data = canvas.collect();
console.log(data);

📄 License

MIT © Lorenzo Coslado

🔗 Links

• GitHub Repository
• NPM Package
• Live Demo