# Fingerprint Modules

The Samhub.js IdGraph system includes three levels of fingerprint modules designed to provide device identification with varying levels of complexity and performance characteristics.

## Overview

Browser fingerprinting collects unique characteristics about a user's device and browser to create a distinctive identifier. The three modules offer different trade-offs between accuracy, performance, and browser compatibility:

| Module | Signals | Performance | Use Case |
|--------|---------|-------------|----------|
| **Basic** | 7 | < 10ms | Fast, lightweight identification |
| **Advanced** | 9+ | 50-200ms | Production-ready comprehensive fingerprinting |
| **Complex** | 12+ | 300-1000ms | Maximum uniqueness for specific use cases |

## Fingerprint Basic Module

### Purpose
Provides fast, lightweight fingerprinting using only stable, instantly-available browser properties.

### Signals Collected
- `fp_basic_screen` - Screen resolution and color depth (e.g., "1920x1080x24")
- `fp_basic_tz` - Timezone offset in minutes
- `fp_basic_lang` - Browser language preference
- `fp_basic_platform` - Operating system platform
- `fp_basic_cores` - Number of CPU cores
- `fp_basic_dpr` - Device pixel ratio
- `fp_basic_hash` - Combined hash of all basic signals

### Performance
- **Execution Time**: < 10ms
- **Browser Support**: All modern browsers
- **Stability**: Very high - signals rarely change

### Usage
```typescript
import { IdGraph } from 'samhub.js';
import IdGraphFingerprintBasicModule from 'samhub.js/idgraph/fingerprint_basic';

const idGraph = new IdGraph('my-container', {
  modules: ['fingerprint_basic']
});

// Or manually
const basicFp = new IdGraphFingerprintBasicModule(idGraph);
await basicFp.collectSignals();
```

### When to Use
- Need fast page load times
- High-traffic websites where performance is critical
- Mobile devices with limited processing power
- When combined with other identification methods (cookies, authentication)

## Fingerprint Advanced Module

### Purpose
Provides comprehensive fingerprinting using proven techniques and the industry-standard FingerprintJS library. Balances accuracy with performance for production use.

### Signals Collected
- `fp_adv_fingerprintjs` - FingerprintJS visitor ID (high-quality fingerprint)
- `fp_adv_confidence` - Confidence score from FingerprintJS
- `fp_adv_canvas` - Canvas rendering fingerprint
- `fp_adv_webgl` - WebGL vendor and renderer information
- `fp_adv_fonts` - System font detection
- `fp_adv_audio` - Audio context characteristics
- `fp_adv_plugins` - Browser plugins signature
- `fp_adv_touch` - Touch capabilities
- `fp_adv_media` - Connected media devices count

### Technology
Uses **[@fingerprintjs/fingerprintjs](https://github.com/fingerprintjs/fingerprintjs)** library v5.0+, which provides:
- Battle-tested fingerprinting algorithms
- Regular updates for new browser versions
- High accuracy and stability
- Comprehensive cross-browser support

### Performance
- **Execution Time**: 50-200ms (typical)
- **Browser Support**: All modern browsers (Chrome, Firefox, Safari, Edge)
- **Stability**: High - FingerprintJS handles browser variations

### Usage
```typescript
import { IdGraph } from 'samhub.js';

const idGraph = new IdGraph('my-container', {
  modules: ['fingerprint_advanced']
});

// The module automatically loads and configures
```

### When to Use
- **Recommended for most production use cases**
- E-commerce fraud prevention
- User analytics and attribution
- A/B testing consistency
- Ad tech and marketing attribution
- When you need reliable device identification

## Fingerprint Complex Module

### Purpose
Provides maximum device uniqueness using experimental and computationally expensive techniques. Use only when highest entropy is required and performance impact is acceptable.

### ⚠️ Warnings
- May take 300-1000ms to complete
- Can cause UI jank on slower devices
- Some techniques may be unreliable across browser versions
- May trigger security warnings in some contexts
- Results may vary significantly between browsers

### Signals Collected
- `fp_complex_webgl_scene` - Complex 3D scene rendering fingerprint
- `fp_complex_fonts` - Exhaustive font detection (200+ fonts)
- `fp_complex_dom_perf` - DOM rendering performance characteristics
- `fp_complex_webrtc_ips` - Local IP addresses via WebRTC
- `fp_complex_battery` - Battery status and level
- `fp_complex_gamepads` - Connected gamepad details
- `fp_complex_canvas_ops` - Complex canvas operations with gradients
- `fp_complex_audio_ops` - Complex audio processing across waveforms
- `fp_complex_shader_timing` - WebGL shader compilation timing
- `fp_complex_media_queries` - Exhaustive CSS media query results
- `fp_complex_client_rects` - Element geometry measurements
- `fp_complex_combined_hash` - SHA-256 hash of all complex signals

### Techniques Used
1. **WebGL Scene Rendering** - Renders complex 3D scene with shaders
2. **Font Detection** - Tests 200+ fonts using measurement technique
3. **WebRTC IP Leakage** - Discovers local network IPs
4. **Battery API** - Captures battery characteristics
5. **Canvas with Effects** - Complex gradients, shadows, and composite operations
6. **Audio Fingerprinting** - Multiple oscillator types with frequency analysis
7. **Shader Compilation Timing** - Measures GPU performance characteristics

### Performance
- **Execution Time**: 300-1000ms (can be longer on slow devices)
- **Browser Support**: Modern browsers only; gracefully degrades
- **Stability**: Medium - some signals may change or be blocked

### Usage
```typescript
import { IdGraph } from 'samhub.js';

const idGraph = new IdGraph('my-container', {
  modules: ['fingerprint_complex']
});

// Consider running only for a sample of users
const shouldRunComplex = Math.random() < 0.1; // 10% of users
if (shouldRunComplex) {
  const complexFp = new IdGraphFingerprintComplexModule(idGraph);
  await complexFp.collectSignals();
}
```

### When to Use
- High-security applications (banking, healthcare)
- Fraud detection where maximum accuracy is needed
- Research and data analysis
- When other identification methods have failed
- When performance impact is acceptable

### When NOT to Use
- Mobile devices
- High-traffic consumer websites
- Real-time applications
- Initial page load
- Low-end devices

## Module Comparison

### Entropy Comparison
Estimated bits of entropy (uniqueness):

- **Basic**: ~15-20 bits (reasonable for basic tracking)
- **Advanced**: ~35-45 bits (high uniqueness for most use cases)
- **Complex**: ~50-60 bits (maximum uniqueness)

### Privacy Considerations

All three modules collect technical browser information only - no personal data. However:

- **Basic**: Minimal privacy concerns - just device characteristics
- **Advanced**: Standard fingerprinting with consent consideration
- **Complex**: May collect network information (IPs) - consider privacy regulations

**Recommendation**: Always disclose fingerprinting in your privacy policy and obtain appropriate consent based on applicable regulations (GDPR, CCPA, etc.).

## Best Practices

### 1. Choose the Right Module
```typescript
// High-traffic consumer site
modules: ['fingerprint_basic']

// Standard web application
modules: ['fingerprint_advanced']  // ✅ Recommended

// High-security financial application
modules: ['fingerprint_advanced', 'fingerprint_complex']
```

### 2. Combine with Other Signals
Fingerprints work best when combined with:
- First-party cookies (`1stparty_cookie` module)
- Authentication data (`auth_session` module)
- Browser info (`browser_info` module)

```typescript
const idGraph = new IdGraph('my-app', {
  modules: [
    '1stparty_cookie',
    'auth_session',
    'browser_info',
    'fingerprint_advanced'  // Add fingerprint layer
  ]
});
```

### 3. Sample for Complex Fingerprinting
```typescript
// Only run complex fingerprinting on 5% of users
const idGraph = new IdGraph('my-app', {
  modules: ['fingerprint_advanced'],
  sampling: 0.05  // 5% of users
});

// Manually add complex fingerprint to that sample
if (shouldRunComplex) {
  const complex = new IdGraphFingerprintComplexModule(idGraph);
  await complex.collectSignals();
}
```

### 4. Handle Errors Gracefully
All modules handle errors silently and continue with available signals:

```typescript
try {
  const fp = new IdGraphFingerprintAdvancedModule(idGraph);
  await fp.collectSignals();
} catch (error) {
  // Errors are caught internally, but you can add logging
  console.warn('Fingerprint collection had issues:', error);
}
```

## Browser Compatibility

| Browser | Basic | Advanced | Complex |
|---------|-------|----------|---------|
| Chrome 90+ | ✅ | ✅ | ✅ |
| Firefox 88+ | ✅ | ✅ | ⚠️ (partial) |
| Safari 14+ | ✅ | ✅ | ⚠️ (partial) |
| Edge 90+ | ✅ | ✅ | ✅ |
| Mobile Chrome | ✅ | ✅ | ⚠️ (slow) |
| Mobile Safari | ✅ | ✅ | ❌ (not recommended) |

Legend:
- ✅ Full support
- ⚠️ Partial support or performance concerns
- ❌ Not recommended

## Installation

The fingerprint modules are included with samhub.js. The advanced module requires the FingerprintJS library:

```bash
npm install samhub.js @fingerprintjs/fingerprintjs
```

Or if already installed, just ensure you have the dependency:

```json
{
  "dependencies": {
    "samhub.js": "^1.0.0",
    "@fingerprintjs/fingerprintjs": "^5.0.0"
  }
}
```

## Examples

### Simple E-commerce Setup
```typescript
const idGraph = new IdGraph('shop-xyz', {
  api_url: 'https://analytics.example.com/pixel.gif',
  modules: ['1stparty_cookie', 'fingerprint_advanced'],
  sampling: 1.0
});
```

### Banking Application
```typescript
const idGraph = new IdGraph('bank-app', {
  api_url: 'https://security.bank.com/track.gif',
  modules: [
    '1stparty_cookie',
    'auth_session',
    'browser_info',
    'fingerprint_advanced'
  ],
  sampling: 1.0
});

// Add complex fingerprint for flagged sessions
if (isHighRiskSession) {
  const complex = new IdGraphFingerprintComplexModule(idGraph);
  await complex.collectSignals();
}
```

### High-Performance News Site
```typescript
const idGraph = new IdGraph('news-site', {
  api_url: 'https://analytics.news.com/pixel.gif',
  modules: ['1stparty_cookie', 'fingerprint_basic'],  // Fast!
  sampling: 1.0,
  flush_interval_ms: 10000  // Batch less frequently
});
```

## Additional Resources

- [FingerprintJS Documentation](https://github.com/fingerprintjs/fingerprintjs)
- [Browser Fingerprinting - Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/Privacy#fingerprinting)
- [Samhub.js Documentation](../../README.md)

## Support

For issues, questions, or contributions, please visit:
- GitHub: [brainnordic/samhub-js](https://github.com/brainnordic/samhub-js)
- Email: support@samhub.io