@vigilkids/device-fingerprint

Browser device fingerprint and platform standard client headers for VigilKids / Visiva frontend applications. Built on FingerprintJS v4 (MIT, open-source).

Features

• Deterministic fingerprint — same hash in normal and incognito mode (canvas/webgl/audio signals)
• Memory-only cache — no cookie/localStorage dependency, recomputes on page load (~50ms)
• Platform headers — generates X-Device-ID, X-Client-Type, X-Client-Platform, X-Product-Code headers
• Multi-product — works with any VigilKids product (vigilkids, visiva, etc.)

Install

pnpm add @vigilkids/device-fingerprint

Usage

Client Headers (recommended)

Most use cases only need getClientHeaders — it computes the fingerprint internally and returns all standard headers:

import { getClientHeaders } from '@vigilkids/device-fingerprint'

const headers = await getClientHeaders({
  productCode: 'visiva',
  appVersion: '1.0.0',  // optional
})
// {
//   'X-Device-ID': 'a1b2c3d4e5f6...',
//   'X-Client-Type': 'web',
//   'X-Client-Platform': 'web',
//   'X-Product-Code': 'visiva',
//   'X-Client-Version': '1.0.0',
// }

Raw Fingerprint

For direct access to the fingerprint result:

import { getDeviceFingerprint } from '@vigilkids/device-fingerprint'

const { visitorId, confidence } = await getDeviceFingerprint()
// visitorId: hex string (FingerprintJS hash)
// confidence: 0-1 (higher = more reliable)

Reset Cache

Force recomputation on next call (typically not needed):

import { resetFingerprint } from '@vigilkids/device-fingerprint'

resetFingerprint()

Exports

| Entry Point | Import | Content | |-------------|--------|---------| | Main | @vigilkids/device-fingerprint | getDeviceFingerprint, getClientHeaders, resetFingerprint | | Types | @vigilkids/device-fingerprint/types | DeviceFingerprintResult, ClientHeaderOptions |

How It Works

getClientHeaders()
  └─ getDeviceFingerprint()
       └─ FingerprintJS.load()  → agent (singleton, cached)
            └─ agent.get()      → { visitorId, confidence }
                                    ↓ (memory cache)
       └─ return cached result
  └─ build headers map with X-Device-ID = visitorId

The fingerprint is computed from browser hardware signals (canvas rendering, WebGL renderer, audio context, etc.). These signals are consistent across normal and incognito sessions on the same device/browser combination.

Backend Integration

The generated headers are consumed by the OneX backend middleware chain:

1. ClientContextMiddleware extracts X-Device-ID → ClientContext.DeviceID
2. SessionService.Create() stores DeviceID in p_identity_sessions.device_id
3. Audit and promotion modules use the device ID for logging and fraud analysis

Compatibility

• Browser only (requires window, document, canvas)
• ESM only
• TypeScript >= 5.0

License

MIT