iph-device-fingerprint

A lightweight reusable Express.js utility and middleware for generating request-based device fingerprints using HTTP request metadata.

Overview

iph-device-fingerprint helps generate a lightweight device fingerprint from incoming request metadata.

The package can:

• generate request fingerprints
• attach fingerprints to requests
• validate request fingerprints
• assist with session verification
• help detect unusual client changes

The library is intentionally lightweight and framework-friendly.

What Is a Device Fingerprint?

A device fingerprint is a derived identifier generated from characteristics of a request or device.

This package builds fingerprints using:

• user-agent
• client IP
• accept
• accept-language

The resulting fingerprint can be used as:

• an additional authentication signal
• a session integrity check
• anomaly detection metadata
• lightweight request verification

Features

Fingerprint Generation

Creates deterministic fingerprints from request metadata.

Fingerprint Verification

Compares incoming requests against previously stored fingerprints.

Express Middleware Support

Automatically attaches fingerprints to request headers.

Lightweight and Dependency-Free

No external fingerprinting services or browser scripts required.

Installation

npm install iph-device-fingerprint

Basic Usage

import express from "express";

import {
  createDeviceFingerprintMiddleware,
} from "iph-device-fingerprint";

const app = express();

app.use(
  createDeviceFingerprintMiddleware(),
);

How Fingerprints Are Built

The package combines:

user-agent
+
client IP
+
accept header
+
accept-language header

into a single fingerprint string.

Example Fingerprint

Mozilla/5.0:127.0.0.1:text/html:en-US

API

buildDeviceFingerprint(req)

Builds a fingerprint string from the incoming request.

Signature

buildDeviceFingerprint(
  req: Request,
): string

Example

import {
  buildDeviceFingerprint,
} from "iph-device-fingerprint";

app.get("/fingerprint", (req, res) => {
  const fingerprint =
    buildDeviceFingerprint(req);

  res.json({
    fingerprint,
  });
});

verifyDeviceFingerprint(req, expected)

Compares the current request fingerprint with a stored fingerprint.

Signature

verifyDeviceFingerprint(
  req: Request,
  expected: string | undefined,
): boolean

Example

import {
  verifyDeviceFingerprint,
} from "iph-device-fingerprint";

app.post(
  "/session/check",
  (req, res) => {
    const expected =
      "stored-fingerprint";

    const matches =
      verifyDeviceFingerprint(
        req,
        expected,
      );

    res.json({
      matches,
    });
  },
);

createDeviceFingerprintMiddleware(headerName?)

Creates Express middleware that attaches the generated fingerprint to a request header.

Signature

createDeviceFingerprintMiddleware(
  headerName?: string,
)

Default Header

x-device-fingerprint

Example

app.use(
  createDeviceFingerprintMiddleware(),
);

Custom Header Example

app.use(
  createDeviceFingerprintMiddleware(
    "x-client-fingerprint",
  ),
);

Middleware Behavior

The middleware:

1. builds the fingerprint
2. attaches it to the request headers
3. forwards execution to the next middleware

Example:

req.headers[
  "x-device-fingerprint"
] = buildDeviceFingerprint(req);

Full Example

import express from "express";

import {
  buildDeviceFingerprint,
  verifyDeviceFingerprint,
  createDeviceFingerprintMiddleware,
} from "iph-device-fingerprint";

const app = express();

app.use(
  createDeviceFingerprintMiddleware(),
);

app.post(
  "/session/check",
  (req, res) => {
    const storedFingerprint =
      "saved-fingerprint";

    const matches =
      verifyDeviceFingerprint(
        req,
        storedFingerprint,
      );

    res.json({
      matches,
    });
  },
);

app.listen(3000);

Internal Implementation

The fingerprint is generated using:

const browser =
  req.headers["user-agent"] ||
  "unknown";

const ip =
  req.ip ||
  req.headers["x-forwarded-for"] ||
  "unknown";

const accept =
  req.headers.accept ||
  "unknown";

const language =
  req.headers["accept-language"] ||
  "unknown";

Combined result:

return `${browser}:${ip}:${accept}:${language}`;

Use Cases

Session Integrity Validation

Detect major client changes during authenticated sessions.

Risk-Based Authentication

Use fingerprints as an additional security signal.

Suspicious Activity Detection

Detect:

• browser changes
• proxy changes
• unusual request environments

Lightweight Device Tracking

Associate sessions with approximate client identity.

Security Recommendations

Do Not Use as Sole Authentication

Device fingerprints should NOT replace:

• passwords
• tokens
• sessions
• MFA

Use fingerprints only as supplementary signals.

Use With HTTPS

Always use HTTPS when transmitting fingerprints.

Combine With Other Security Layers

Recommended stack:

HTTPS
↓
Replay Protection
↓
HMAC Verification
↓
Device Fingerprinting
↓
Authentication

Limitations

IP Address Changes

Mobile networks, VPNs, and proxies can change IP addresses frequently.

This may alter fingerprints unexpectedly.

Browser Updates

Browser updates can modify:

• user-agent strings
• accepted formats
• language settings

Not a Permanent Device Identity

This package provides:

• lightweight request fingerprints
• not stable hardware identifiers

Reverse Proxy Considerations

When behind proxies:

• configure Express trust proxy settings
• validate forwarded IP headers carefully

Example:

app.set("trust proxy", true);

Performance

The library is extremely lightweight.

Operations performed:

• simple header reads
• string concatenation
• equality comparison

No hashing or heavy computation is performed.

Best Practices

• combine with authentication systems
• use alongside replay protection
• store fingerprints securely
• avoid treating fingerprints as unique identities
• rotate sessions on major fingerprint changes

Example Security Workflow

Request Received
↓
Replay Protection
↓
Signature Validation
↓
Device Fingerprint Check
↓
Authentication
↓
Application Logic

Example Response

{
  "matches": true
}

License

MIT

Author

Published by: Prashant Srivastav

Package

https://www.npmjs.com/package/iph-device-fingerprint