impaya-fingerprint

Browser fingerprint collector. Gathers 21 signal groups from the browser environment, serializes them deterministically, and returns a SHA-256 hash — ready to send to your backend.

Install

npm install impaya-fingerprint

Usage

import { createFingerprintClient } from 'impaya-fingerprint';

const fp = createFingerprintClient({ projectId: 'your-project-id' });
const { projectId, raw, rawHash, meta } = await fp.collect();

// Send to your backend
await fetch('/api/fingerprint', {
 method: 'POST',
 body: JSON.stringify({ projectId, raw, rawHash, meta }),
});

collect() returns:

| Field | Type | Description | | ----------- | ----------------- | --------------------------------------------------------------------------------- | | projectId | string | The project ID passed to the constructor | | raw | FingerprintData | Collected signal data | | rawHash | string | SHA-256 of raw, keys sorted deterministically | | meta | MetaData | Collection timestamp, duration, session ID, visitor ID — not included in the hash |

collectStable()

Returns the same data with volatile fields nulled out and a SHA-256 of the result. Useful for testing stability locally; on production the stable hash is normally computed server-side.

const { projectId, stable, stableHash, meta } = await fp.collectStable();

collectStable() returns:

| Field | Type | Description | | ------------ | ----------------------- | -------------------------------------------------- | | projectId | string | The project ID passed to the constructor | | stable | StableFingerprintData | Raw data with volatile fields nulled out | | stableHash | string | SHA-256 of stable, keys sorted deterministically | | meta | MetaData | Same as collect() — not included in the hash |

Volatile fields that are nulled in stable:

| Group | Fields nulled | Fields kept | | ----------- | ------------------------------------------------------------------------------------- | ---------------------------------------- | | navigator | userAgent, appVersion, onLine | platform, language, hardwareConcurrency… | | uaCH | fullVersionList, uaFullVersion; platformVersion → major only | brands, platform, architecture… | | screen | availWidth, availHeight, innerWidth, innerHeight, outerWidth, outerHeight | width, height, colorDepth… | | locale | currentTime | timezone, timezoneOffset, locale… | | network | effectiveType, downlink, rtt, saveData | supported | | battery | level, charging, chargingTime, dischargingTime | supported |

meta fields:

| Field | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | visitorId | Persistent 16-character hex ID, stored across all available browser storages. Survives storage clears as long as at least one storage remains intact. | | sessionId | Random ID stable for the lifetime of this FingerprintClient instance. | | collectedAt | ISO timestamp of the collection. | | collectDurationMs | How long collect() took in milliseconds. |

Signals collected

| Group | What it captures | | ------------------ | -------------------------------------------------------------------- | | navigator | UA string, language, hardware concurrency, plugins, DNT | | uaCH | User-Agent Client Hints (high-entropy: architecture, platform, etc.) | | screen | Resolution, color depth, pixel ratio, orientation | | webgl | Vendor, renderer, extensions, unmasked GPU strings | | webgl2 | Max samples, uniform blocks, color attachments | | canvas | 2D render hash | | audio | OfflineAudioContext oscillator signature | | fonts | 70 fonts probed via canvas measurement | | math | JS engine floating-point quirks (sin, cos, tan, …) | | webrtc | Local IP addresses via STUN | | network | Connection effective type, downlink, RTT | | locale | Timezone, offset, locale, calendar, numbering system | | permissions | Status of 10 permission descriptors | | features | 19 API availability flags (WebAssembly, WebAuthn, etc.) | | storage | Storage quota and usage | | battery | Charge level, charging state, time estimates | | mediaDevices | Device counts by kind | | speechVoices | Voice count, languages, sample names | | sensors | Touch, pointer, hover, motion events, media preferences | | colorGamut | sRGB / P3 / Rec2020 support | | browserDetection | Chrome / Firefox / Safari / Edge heuristics |

Design notes

• Hash is deterministic. Object keys are sorted recursively before serialization — the same browser state always produces the same hash.
• meta is not hashed. Timestamps, duration, and identifiers are returned separately so they don't affect rawHash.
• visitorId is redundant by design. It is written to localStorage, sessionStorage, cookies, IndexedDB, and CacheStorage on every call. If any storage is cleared, the ID is restored from the others on the next visit.
• Stable hash is computed from nulled-out data. Volatile fields (UA string, timestamps, network conditions) are zeroed before hashing so the result is stable across page loads. collectStable() exposes this on the client; on production it is normally recomputed server-side for verification.
• No runtime dependencies. SHA-256 uses crypto.subtle; visitor ID generation uses crypto.getRandomValues.
• ESM only, targeting ES2020+.

TypeScript

Full types are included.

import type { FingerprintData, MetaData, CollectResult, StableCollectResult, StableFingerprintData } from 'impaya-fingerprint';

License

MIT