Device Fingerprint

Last updated


This page explains how the device fingerprint that tokens are bound to is generated, where it is checked, and how detection actually behaves.

Generation


CreateFingerprint() (src/CreateFingerprint.ts) builds a JSON object from these four values and takes its SHA-256 hex digest:
FieldSource
osUser-Agent match
browserUser-Agent match
deviceUser-Agent match
deviceIdX-Device-ID header → req.body.deviceId → "Unknown"

When req.session.fp exists (for example, stored yourself with express-session), every API uses it instead of recomputing.

Detection Rules


Matching runs top to bottom and the first hit wins:
FieldOrder
osWindows → Macintosh|Mac OS X → Linux → Android → iPhone|iPad|iPod → Unknown_OS
browserEdge|Edg → Firefox → Chrome → Safari → Opera|OPR → Unknown_Browser
deviceiPad → iPhone|iPod|Android.*Mobile|BlackBerry|IEMobile|Opera Mini → Desktop

Because matching stops at the first hit, some results are counterintuitive:
User-AgentActual resultWhy
Androidos: LinuxAndroid UAs contain Linux, which is checked before Android
iPhone / iPados: MacOSiOS UAs contain like Mac OS X
Operabrowser: ChromeOpera UAs contain Chrome

These values only feed the hash; binding works as long as the same device produces the same result each time.

Where It Is Checked


WhenResult on mismatch
fp in a valid Access TokenisError: true
fp decoded from an expired Access TokenisError: true
fp in Redis refresh dataisError: false (guest)

Related: Token Transport, Client Integration
中文