How l1ttps/nestjs-fingerprint works
Project Type and Purpose
• This is an open-source NestJS dynamic module (“nestjs-fingerprint”) that provides server-side browser/device fingerprinting for any NestJS application.
• It supplies middleware to compute a fingerprint on each HTTP request, sets a cookie, and offers decorators to inject the fingerprint (and real IP) into controller methods.
File-Structure Highlights
• src/nestjs-fingerprint.module.ts – the dynamic NestJS module entry point (forRoot configuration)
• src/middlewares/nestjs-fingerprint.middleware.ts – middleware that runs on each request
• src/decorators/*.ts – @Fingerprint() and @RealIp() parameter decorators
• src/core/generateFingerprint.ts – core fingerprint computation logic
• src/helpers/uniqueParams.ts – utility for normalizing parameters
• example/ – a minimal NestJS app showing module integration
• tests/ – unit and e2e tests validating middleware, helper, and decorator behavior
Main Components
A. Host NestJS Application
• AppModule imports NestjsFingerprintModule.forRoot(…)
• Controllers (e.g. AppController) annotated with @Fingerprint() / @RealIp()
B. Nestjs-Fingerprint Dynamic Module
• Configuration (params list, cookieOptions)
• Middleware registration
• Decorators registration as custom parameter decorators
• Providers (if any shared services or tokens)
C. Middleware Flow
• Incoming HTTP Request
• Middleware extracts headers, userAgent, IP
• Calls generateFingerprint() to produce fingerprint object
• Attaches fingerprint to Request context and sets cookie on HTTP Response
• Passes control to the next handler
D. Decorator Flow
• Controller method decorated with @Fingerprint() reads fingerprint from Request context
• @RealIp() reads the extracted IP value
Interactions & Data Flow
1. Client → HTTP Request → NestJS HTTP Server
2. NestJS Core → Executes FingerprintMiddleware
– Extract config params (headers, UA, IP)
– Call generateFingerprint()
– Store result on request.fp, set response cookie
3. NestJS Core → Controller Handler
– @Fingerprint() decorator fetches request.fp and injects into method argument
– @RealIp() decorator fetches request.fp.ipAddress and injects
4. Controller returns data → HTTP Response to Client
Architectural Patterns & Principles
• NestJS Module Pattern (dynamic module with forRoot configuration)
• Middleware for cross-cutting concerns (fingerprint generation)
• Custom Parameter Decorators for seamless injection into controllers
• Functional decomposition: core logic (generateFingerprint) separated from NestJS specifics
• Extensibility: developer can supply which params to include and cookie options