EmbermindFingerprint

EmbermindFingerprint is a comprehensive browser fingerprinting JavaScript library for fraud detection and visitor identification.

🆓 The library is open source (MIT) and provides best-in-class browser fingerprinting technology that can be used commercially.

Key Features

• Advanced browser fingerprinting with 20+ components
• WebAssembly-based timing attacks for VM detection
• Encrypted fingerprint export with AES-256-GCM
• Canvas, WebGL, and Audio fingerprinting
• Hardware and system detection
• Font and plugin enumeration
• Permission and locale tracking

Performance

The library provides strong fingerprint uniqueness for distinguishing browsers and devices. Results vary based on your audience and use case.

Import from jsDelivr

Transpiled bundles are available on JSDelivr.

Supported module formats:

• UMD: https://cdn.jsdelivr.net/npm/@embermind/embermind-fingerprint/dist/embermind-fingerprint.umd.js
• CommonJS: https://cdn.jsdelivr.net/npm/@embermind/embermind-fingerprint/dist/embermind-fingerprint.cjs.js
• ESM: https://cdn.jsdelivr.net/npm/@embermind/embermind-fingerprint/dist/embermind-fingerprint.esm.js

You can test this in the developer console:

import('https://cdn.jsdelivr.net/npm/@embermind/embermind-fingerprint/dist/embermind-fingerprint.umd.js')
.then(() => {
  const fp = new EmbermindFingerprint.Fingerprint();
  fp.get().then((res) => {
      console.log(res)
  })
})

Install with NPM

npm install @embermind/embermind-fingerprint

⚠️ The fingerprinting needs to run in a browser context. The library requires browser APIs to calculate components.

Encrypted Fingerprint Export

EmbermindFingerprint provides an encrypted export feature that returns only encrypted data and a fingerprint hash. Raw fingerprint components are never exposed.

Installation

npm install @embermind/embermind-fingerprint @noble/ciphers @noble/hashes

Usage

import { getFingerprintEncrypted, Fingerprint } from '@embermind/embermind-fingerprint';

// Standalone function
const result = await getFingerprintEncrypted();
console.log(result.fingerprint);      // HMAC-SHA256 hash (hex)
console.log(result.encryptedData);    // Base64 encrypted data

// Class method
const fp = new Fingerprint();
const result = await fp.getEncrypted();

Return Format

interface EncryptedFingerprintResult {
  encryptedData: string;  // Base64(nonce[12] + ciphertext + tag[16])
  fingerprint: string;     // HMAC-SHA256 hex (64 chars)
}

Fingerprint Hash

The fingerprint is computed as: HMAC-SHA256(JSON.stringify(components), hmacKey)

• Uses @noble/hashes (NOT Web Crypto API) - fully obfuscatable
• Computed BEFORE encryption
• Separate key from encryption key
• Deterministic: same data = same hash
• Can be used for:
  • Server-side deduplication
  • Integrity verification
  • User identification

Security Features

• Encryption: AES-256-GCM via @noble/ciphers
• Fingerprint: HMAC-SHA256 via @noble/hashes
• Two separate keys: One for encryption, one for HMAC
• No Web Crypto for HMAC: Fully obfuscatable - cannot be intercepted
• Privacy: Raw components never exposed in API

Key Management

# Generate TWO separate keys (automatic - no manual copying needed!)
node scripts/generate-aes-key.js

# Rebuild library (keys are embedded at build time)
npm run build

How it works:

1. Script generates .embermind-keys.json (build-time keys)
2. Script generates .embermind-keys.txt (server-side reference)
3. Rollup embeds keys from JSON into bundle at build time
4. Both files are in .gitignore automatically

Important: Store .embermind-keys.txt securely - it contains keys for server-side decryption!

Browser Compatibility

Requires CompressionStream API for gzip compression:

• Chrome: 80+ (Feb 2020)
• Firefox: 113+ (May 2023)
• Safari: 16.4+ (March 2023)

Bundle Size

Adds approximately 20KB to your bundle:

• @noble/ciphers: ~15KB (AES-256-GCM)
• @noble/hashes: ~3KB (HMAC-SHA256)
• Utilities: ~2KB

Security Considerations

• Client-side limitation: Keys are in source code and can be extracted by determined attackers
• Use HTTPS: Always transmit encrypted data over secure connections
• Server validation: Add timestamp checks and rate limiting on server
• Key rotation: Regenerate keys and rebuild every 1-2 months for enhanced security
• Code obfuscation: Consider adding code obfuscation (e.g., javascript-obfuscator or Jscrambler) for additional protection

This encryption provides basic protection and data privacy during transmission. While it makes casual inspection and automated attacks significantly more difficult, it should not be considered cryptographically unbreakable in a client-side environment where motivated attackers have full access to the code.

Options

Options are passed to the Fingerprint class constructor:

const fp = new EmbermindFingerprint.Fingerprint({
  option_key: option_value
})

| option | type | example | what it does | | - | - | - | - | | api_key | string | 'ae8679607bf79f......' | API key for server-side components | exclude | string[] | ['webgl', 'system.browser.version'] | Removes components from the fingerprint hash. An excluded top-level component improves performance. | | include | string[] | ['webgl', 'system.browser.version'] | Only includes the listed components. exclude still excludes included components. | | permissions_to_check | string[] | ['gyroscope', 'accelerometer'] | Checks only selected permissions. | | timeout | integer | 5000 | Component timeout in milliseconds (default: 5000). | logging | boolean | true | Enable/disable logging (default: true). | | performance | boolean | false | Include performance timing data (default: false). | | stabilize | string[] | ['private', 'iframe'] | Preset exclusion list for different scenarios.

Example usage:

const fp = new EmbermindFingerprint.Fingerprint({
    exclude: ['math']
});

Custom components

You can add custom components with includeComponent, which takes the component key and a function that returns the value (string, number, or JSON object).

Components included in fingerprint

• audio fingerprint
• canvas fingerprint
• webgl fingerprint
• available fonts and how they render
• videocard
• browser languages and time zone
• browser permissions
• available plugins
• a ton of screen details including media queries
• TLS handshake details (API only)
• HTTP headers (API only)
• Connection/IP details (API only)

Technical details

The library has a simple, extensible structure. See technical_details for more information about how it works.