Express Server-Side Fingerprinting Middleware

1.2.2 · active · verified Wed Apr 22

express-fingerprint is an Express middleware designed for passive, server-side client fingerprinting. It allows developers to identify incoming requests based on characteristics observable in HTTP request contents without executing any client-side code. The current stable version is `1.2.2`. The library processes information such as the User-Agent string, HTTP Accept headers, and GeoIP data (if available) to generate a unique hash and a detailed component breakdown for each request, accessible via `req.fingerprint`. Releases are infrequent but have recently addressed critical import issues and added TypeScript support. A key differentiator is its strict adherence to server-side data collection, prioritizing privacy by avoiding client-side scripts, and offering extensibility through custom parameter functions to gather additional request-specific data.

Common errors

```
TypeError: Fingerprint is not a function
```
cause Attempting to use `Fingerprint` as a constructor or function after incorrectly importing it as a named export from a default-exported module.

fix Adjust your import statement to correctly get the default export: `import Fingerprint from 'express-fingerprint'` (ESM) or `const Fingerprint = require('express-fingerprint')` (CommonJS).
```
Error: Cannot find module 'express-fingerprint'
```
cause The package is either not installed, or the Node.js runtime cannot locate it due to incorrect path resolution or corrupted `node_modules`.

fix Run `npm install express-fingerprint` to ensure the package is installed. If the error persists, clear your `node_modules` and `package-lock.json` and reinstall dependencies.
```
TypeError: Cannot read properties of undefined (reading 'fingerprint')
```
cause The `express-fingerprint` middleware has not been correctly applied to the Express app, or `req.fingerprint` is being accessed before the middleware has had a chance to execute.

fix Ensure `app.use(Fingerprint(...))` is called *before* any routes or other middleware that attempt to access `req.fingerprint`. Verify there are no errors in the middleware's initialization.

Warnings

breaking The `require('express-fingerprint')` statement was not working correctly in some versions prior to `1.2.2`, leading to import errors for CommonJS users.
Fix: Ensure you are using version `1.2.2` or later. If upgrading, verify your `require` statements are consistent with a default export (`const Fingerprint = require('express-fingerprint')`).
gotcha Custom fingerprint parameters are asynchronous and require a specific callback pattern (`next(null, { key: 'value' })`). Incorrect use can prevent data from being added or halt the middleware chain.
Fix: Always invoke `next(null, dataObject)` with `dataObject` containing the properties you wish to add to the fingerprint component. Ensure `dataObject` is a plain object.
gotcha The library primarily uses a default export. Attempting to destructure it as a named import in ESM (`import { Fingerprint } from 'express-fingerprint'`) or CommonJS (`const { Fingerprint } = require('express-fingerprint')`) will result in `undefined` or a `TypeError`.
Fix: For ESM, use `import Fingerprint from 'express-fingerprint'`. For CommonJS, use `const Fingerprint = require('express-fingerprint')`. Static properties like `Fingerprint.useragent` are accessed directly on the default export.

Install

npm install express-fingerprint npm
yarn add express-fingerprint yarn
pnpm add express-fingerprint pnpm

Imports

Fingerprint
wrong:
```
import { Fingerprint } from 'express-fingerprint'
```
correct:
```
import Fingerprint from 'express-fingerprint'
```
Since v1.2.0, the package primarily uses a default export. Use named imports only for static properties like `Fingerprint.useragent`.
Fingerprint
wrong:
```
const { Fingerprint } = require('express-fingerprint')
```
correct:
```
const Fingerprint = require('express-fingerprint')
```
CommonJS usage requires importing the default export directly. Fixes for this specific `require` pattern were included in v1.2.2.
Fingerprint.useragent
```
import Fingerprint from 'express-fingerprint'; // Then use Fingerprint.useragent
```
Static properties like `useragent`, `acceptHeaders`, and `geoip` are accessed directly on the default `Fingerprint` export, not as named imports.

Quickstart

This quickstart demonstrates how to initialize `express-fingerprint` as middleware, including default and custom parameters, and how to access the generated fingerprint object on the `req` object for every incoming request.

import express from 'express';
import Fingerprint from 'express-fingerprint';

const app = express();

app.use(Fingerprint({
    parameters: [
        // Default parameters
        Fingerprint.useragent,
        Fingerprint.acceptHeaders,
        Fingerprint.geoip,

        // Custom additional parameters
        function(next) {
            // Example: Add a custom header value
            const customHeader = this.req.headers['x-custom-id'] || 'N/A';
            next(null, {
                'customHeaderId': customHeader
            });
        },
        function(next) {
            // Example: Asynchronously fetch and add data
            setTimeout(() => {
                next(null, {
                    'customAsyncParam': 'asyncValue'
                });
            }, 50);
        }
    ]
}));

app.get('/', (req, res) => {
    // The fingerprint object is available on req.fingerprint
    console.log('Request Fingerprint:', req.fingerprint);
    res.json({
        message: 'Fingerprint collected!',
        fingerprint: req.fingerprint
    });
});

app.listen(3000, () => {
    console.log('Server listening on http://localhost:3000');
});

view raw JSON →