Fingerprinting

Every time a sensitive request reaches the IAM service, the getFingerPrint middleware extracts a composite device fingerprint from the incoming request. The fingerprint combines IP-based geolocation data (country, city, coordinates, ISP, proxy/hosting flags) with parsed user-agent fields (browser, OS, device type, vendor, model) and a bot detection signal. This data is attached to req.fingerPrint and flows into three downstream systems: anomaly detection, MFA verification, and visitor trust management.

The fingerprint is not a browser-side fingerprint (no canvas hashing, no WebGL probing). It is a server-side composite built entirely from request headers and IP metadata. The service compares incoming fingerprints against stored visitor records to detect device changes, geographic shifts, and suspicious infrastructure usage.

Data collection

The getFingerPrint middleware runs on every route that involves session verification, token rotation, or MFA. It calls two functions from the Bot Detector package: getGeoData for IP geolocation and parseUA for user-agent parsing.

import { getFingerPrint } from '@riavzon/auth'

// Mount on any route that needs fingerprint data
router.post('/sensitive-action', getFingerPrint, async (req, res) => {
  const { ipAddress, country, city, browser, os, device } = req.fingerPrint
  // ...
})

The middleware populates req.fingerPrint with the full FingerPrint interface:

Geolocation fields

User-agent fields

Where fingerprints are collected

The getFingerPrint middleware is mounted on routes where the service needs to verify or update the client's identity:

Visitor persistence

When a user completes MFA verification or logs in from a new device, the service calls updateVisitors from the Bot Detector package to persist the fingerprint to the visitors table. This stored record becomes the baseline for future anomaly comparisons.

The visitors table stores one record per visitor_id (linked to the canary_id cookie). Each record contains the full set of geolocation and user-agent fields from the FingerPrint interface. When updateVisitors is called, it overwrites the stored record with the current request's fingerprint data.

When fingerprints are persisted

trustVisitor

trustVisitor is called when a user verifies a new device through MFA. It performs two operations inside a single database transaction:

1. Updates the user's visitor_id to point to the newly verified visitor record
2. Calls updateVisitors to persist the current fingerprint to that visitor record

If updateVisitors fails, the transaction rolls back and the user's visitor_id is not updated. This ensures the user is never associated with a visitor record that has incomplete fingerprint data.

import { trustVisitor } from '@riavzon/auth'

const result = await trustVisitor(
  userId,
  visitorIdToTrust,
  canaryId,
  req.fingerPrint,
  log
)

if (!result.ok) {
  // Transaction failed — visitor not trusted
  log.error(result.data)
}

Anomaly detection integration

The stored fingerprint is the reference point for anomaly detection. When strangeThings() runs on a refresh-token use, it joins the refresh_tokens, users, and visitors tables to compare the incoming request against the stored visitor record.

The following fingerprint fields are compared:

The canary_id lifecycle

The canary_id is a long-lived browser cookie that serves as the persistent device identifier. It ties a specific browser instance to a visitor_id in the database.

Accessing fingerprints in custom handlers

After the getFingerPrint middleware runs, the full fingerprint is available on req.fingerPrint. Use it for logging, analytics, or custom security logic.

import { getFingerPrint } from '@riavzon/auth'

router.post('/transfer',
  getFingerPrint,
  async (req, res) => {
    const fp = req.fingerPrint

    // Log the request context
    log.info({
      ip: fp.ipAddress,
      country: fp.country,
      browser: fp.browser,
      device: fp.device,
      proxy: fp.proxy,
    }, 'Transfer request')

    // Block requests from hosting providers
    if (fp.hosting) {
      return res.status(403).json({ error: 'Requests from hosting providers are not allowed.' })
    }

    // Include location in the confirmation email
    const location = [fp.city, fp.regionName, fp.country].filter(Boolean).join(', ')

    await sendConfirmationEmail(user.email, {
      amount: req.body.amount,
      location,
      device: `${fp.browser} on ${fp.os}`,
    })
  }
)