feat(figerprinting): add test coverage, improve fingerprinting, and update README

Author: Nekzus

README.md

@@ -1,23 +1,38 @@
 # Tokenly 🔐
 
+[![Github Workflow](https://github.com/nekzus/tokenly/actions/workflows/publish.yml/badge.svg?event=push)](https://github.com/Nekzus/tokenly/actions/workflows/publish.yml)
+[![npm-version](https://img.shields.io/npm/v/@nekzus/tokenly.svg)](https://www.npmjs.com/package/@nekzus/tokenly)
+[![npm-month](https://img.shields.io/npm/dm/@nekzus/tokenly.svg)](https://www.npmjs.com/package/@nekzus/tokenly)
+[![npm-total](https://img.shields.io/npm/dt/@nekzus/tokenly.svg?style=flat)](https://www.npmjs.com/package/@nekzus/tokenly)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 <div align="center">
 
-[![npm version](https://badge.fury.io/js/@nekzus%2Ftokenly.svg)](https://www.npmjs.com/package/@nekzus/tokenly)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+**Advanced JWT Token Management with Device Fingerprinting**
 
-**Secure JWT token management with advanced device fingerprinting**
-
-_Security by default, enhanced with device fingerprinting_
+_Enterprise-grade security by default for modern applications_
 
 </div>
 
+## Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Security Features](#security-features)
+- [API Reference](#api-reference)
+- [Environment Variables](#environment-variables--secrets)
+- [Best Practices](#best-practices)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## ✨ Features
 
-- **🛡️ Security by Default**: JWT tokens with built-in security features
-- **🔒 Device Control**: Advanced fingerprinting system for device tracking
-- **🚀 Easy Integration**: Simple API that works seamlessly with Express
-- **⚡ Performance**: Optimized token generation and validation
-- **🛠️ Configurable**: Flexible settings to match your security needs
+- **Zero Configuration Required**: Works out of the box with secure defaults
+- **Device Fingerprinting**: Unique identification of devices to prevent token theft
+- **Framework Agnostic**: Use with Express, Fastify, Koa, or any Node.js framework
+- **TypeScript First**: Full type safety and excellent IDE support
+- **Production Ready**: Built for enterprise applications
 
 ## 📦 Installation
 
@@ -28,140 +43,204 @@ npm install @nekzus/tokenly
 ## 🚀 Quick Start
 
 ```typescript
-import { Tokenly } from '@nekzus/tokenly';
+import { Tokenly, getClientIP } from '@nekzus/tokenly';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
 
-// Initialize with fingerprinting enabled
+// Initialize Tokenly
 const auth = new Tokenly({
-  accessTokenExpiry: '15m',
-  securityConfig: {
-    enableFingerprint: true,
-    maxDevices: 5
-  }
+    accessTokenExpiry: '15m',
+    refreshTokenExpiry: '7d',
+    securityConfig: {
+        enableFingerprint: true,
+        maxDevices: 5
+    }
 });
 
-// Generate a token with device fingerprinting
-const token = auth.generateAccessToken(
-    { userId: '123' },
-    undefined,
-    {
-        userAgent: req.headers['user-agent'] || '',
-        ip: getClientIP(req)
+// Generate token with fingerprinting
+app.post('/login', (req, res) => {
+    const token = auth.generateAccessToken(
+        { userId: '123', role: 'user' },
+        undefined,
+        {
+            userAgent: req.headers['user-agent'] || '',
+            ip: getClientIP(req.headers)
+        }
+    );
+    res.json({ token });
+});
+```
+
+## 🔧 Configuration
+
+### Basic Configuration
+```typescript
+const auth = new Tokenly({
+    accessTokenExpiry: '15m',    // 15 minutes
+    refreshTokenExpiry: '7d',    // 7 days
+    securityConfig: {
+        enableFingerprint: true,  // Enable device tracking
+        maxDevices: 5            // Max devices per user
     }
-);
+});
 ```
 
-## 📘 API Reference
+### Advanced Security Configuration
+```typescript
+const auth = new Tokenly({
+    accessTokenExpiry: '5m',     // Shorter token life
+    refreshTokenExpiry: '1d',    // Daily refresh required
+    securityConfig: {
+        enableFingerprint: true,  // Required for device tracking
+        enableBlacklist: true,    // Enable token revocation
+        maxDevices: 3            // Strict device limit
+    }
+});
+```
 
-### Configuration
+## 🛡️ Security Features
 
+### Device Fingerprinting
+- **User Agent**: Browser/client identification
+- **IP Address**: Client's IP address
+- **Cryptographic Salt**: Unique per instance
+- **Consistent Hashing**: Same device = Same fingerprint
+
+### Token Management
+- **Access Tokens**: Short-lived JWTs for API access
+- **Refresh Tokens**: Long-lived tokens for session maintenance
+- **Blacklisting**: Optional token revocation support
+- **Expiration Control**: Configurable token lifetimes
+
+### Security Events
 ```typescript
-interface TokenlyConfig {
-    // Token expiration time (default: '15m')
-    accessTokenExpiry?: string;
-    
-    // Security settings
-    securityConfig?: {
-        // Enable device fingerprinting (default: false)
-        enableFingerprint?: boolean;
-        // Maximum devices per user (default: 5)
-        maxDevices?: number;
-    };
-}
+// Invalid Fingerprint Detection
+auth.on('invalid_fingerprint', (event) => {
+    console.log(`Security Alert: Invalid fingerprint detected`);
+    console.log(`User: ${event.userId}`);
+    console.log(`IP: ${event.context.ip}`);
+});
+
+// Device Limit Reached
+auth.on('max_devices_reached', (event) => {
+    console.log(`Device limit reached for user: ${event.userId}`);
+    console.log(`Current devices: ${event.context.currentDevices}`);
+});
 ```
 
+## 📘 API Reference
+
 ### Token Generation
+```typescript
+const token = auth.generateAccessToken(
+    payload: { userId: string; role: string },
+    options?: { fingerprint?: string; deviceId?: string },
+    context?: { userAgent: string; ip: string }
+);
+```
 
+### IP Detection Helper
 ```typescript
-// Helper for reliable IP detection
-function getClientIP(req: express.Request): string {
-    const forwardedFor = req.headers['x-forwarded-for'];
-    if (typeof forwardedFor === 'string') {
-        return forwardedFor.split(',')[0].trim();
-    }
-    return req.ip || '';
-}
+import { getClientIP } from '@nekzus/tokenly';
 
-// Express implementation example
-app.post('/login', async (req, res) => {
-    try {
-        const token = auth.generateAccessToken(
-            { userId: user.id },
-            undefined,
-            {
-                userAgent: req.headers['user-agent'] || '',
-                ip: getClientIP(req)
-            }
-        );
-        res.json({ token });
-    } catch (error) {
-        res.status(400).json({ error: error.message });
-    }
-});
+const clientIP = getClientIP(headers, defaultIP);
 ```
 
-### Token Structure
+Priority order:
+1. `X-Real-IP`: Direct proxy IP
+2. `X-Forwarded-For`: First IP in proxy chain
+3. Default IP (if provided)
+4. Empty string (fallback)
 
+### Type Definitions
 ```typescript
 interface AccessToken {
-    // JWT token string
     raw: string;
-    
-    // Token payload
     payload: {
         userId: string;
-        fingerprint?: string;  // Present when fingerprinting is enabled
-        aud: string;          // 'tokenly-client'
-        iss: string;          // 'tokenly-auth'
-        iat: string;          // Issue timestamp
-        exp: string;          // Expiration timestamp
+        role: string;
+        [key: string]: any;
     };
 }
-```
 
-## 🔒 Security Best Practices
+interface InvalidFingerprintEvent {
+    type: 'invalid_fingerprint';
+    userId: string;
+    token: string;
+    context: {
+        expectedFingerprint: string;
+        receivedFingerprint: string;
+        ip: string;
+        userAgent: string;
+        timestamp: string;
+    };
+}
 
-### Device Fingerprinting
-- **Unique Identification**: Each device is uniquely identified by its IP and User-Agent combination
-- **Consistent Tracking**: Same device will generate the same fingerprint across sessions
-- **Fraud Prevention**: Helps detect and prevent unauthorized access attempts
+interface MaxDevicesEvent {
+    type: 'max_devices_reached';
+    userId: string;
+    context: {
+        currentDevices: number;
+        maxAllowed: number;
+        ip: string;
+        userAgent: string;
+        timestamp: string;
+    };
+}
+```
 
-### IP Detection
-- Always handle `X-Forwarded-For` headers properly in proxy environments
-- Use the first IP in the chain as it represents the original client
-- Implement appropriate fallbacks for direct connections
+## 🔑 Environment Variables & Secrets
 
-### User Agent Handling
-- Use complete User-Agent strings for maximum accuracy
-- Provide fallbacks for empty values
-- Maintain original User-Agent format
+### Required Variables
+```env
+# .env
+JWT_SECRET_ACCESS=your_secure_access_token_secret
+JWT_SECRET_REFRESH=your_secure_refresh_token_secret
+```
 
-## 📚 Examples
+When environment variables are not provided, Tokenly automatically:
+- Generates cryptographically secure random secrets
+- Uses SHA-256 for secret generation
+- Implements secure entropy sources
+- Creates unique secrets per instance
 
-### Basic Implementation
-```typescript
-const auth = new Tokenly();
+> ⚠️ **Important**: While auto-generated secrets are cryptographically secure, they regenerate on each application restart. This means all previously issued tokens will become invalid. For production environments, always provide permanent secrets through environment variables.
 
-// Generate token
-const token = auth.generateAccessToken({ userId: '123' });
+### Secret Generation
+```bash
+# Generate secure random secrets
+node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
 ```
 
-### With Fingerprinting
-```typescript
-const auth = new Tokenly({
-    securityConfig: { enableFingerprint: true }
-});
+### Security Guidelines
+- Never commit secrets to version control
+- Use different secrets for development and production
+- Minimum length of 32 characters recommended
+- Rotate secrets periodically in production
+- Use secret management services when available
 
-// Generate token with device tracking
-const token = auth.generateAccessToken(
-    { userId: '123' },
-    undefined,
-    { userAgent, ip }
-);
-```
+## 🔐 Best Practices
+
+### Token Security
+- Use short-lived access tokens (5-15 minutes)
+- Implement refresh token rotation
+- Enable blacklisting for critical applications
+
+### Device Management
+- Enable fingerprinting for sensitive applications
+- Set reasonable device limits per user
+- Monitor security events
+
+### IP Detection
+- Configure proxy headers correctly
+- Use `X-Real-IP` for single proxy setups
+- Handle `X-Forwarded-For` for proxy chains
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
 ## 📄 License
 

biome.json

@@ -4,7 +4,7 @@
     "enabled": true
   },
   "files": {
-    "include": ["src/**/*.{ts,tsx,js,jsx,json}"],
+    "include": ["src/**/*.{ts,tsx,js,jsx,json}", "tests/**/*.{ts,tsx,js,jsx,json}"],
     "ignore": ["node_modules", "dist", "examples"]
   },
   "linter": {

dist/index.cjs

@@ -1,3 +1,3 @@
 export { Tokenly } from './tokenManager.js';
-export type { AccessToken, TokenlyConfig } from './types.js';
+export type { AccessToken, Headers, InvalidFingerprintEvent, MaxDevicesEvent, TokenContext, TokenlyConfig } from './types.js';
 export { getClientIP } from './utils/ipHelper.js';

dist/index.cjs.map

@@ -68,12 +68,13 @@ export declare class Tokenly {
     private eventListeners;
     private autoRotationInterval;
     private fingerprintCache;
-    private readonly instanceSalt;
+    private readonly instanceId;
     /**
      * Initialize Tokenly with custom configuration
      * @param config Optional configuration for token management
      */
     constructor(config?: TokenlyConfig);
+    private generateSecret;
     /**
      * Format Unix timestamp to ISO date string
      * @param timestamp Unix timestamp in seconds

dist/index.js

@@ -1,6 +1,8 @@
+import { Headers } from '../types.js';
 /**
  * Helper function to get the real client IP from various headers
  * @param headers Object containing HTTP headers
+ * @param defaultIP Optional default IP if no headers found
  * @returns string Client IP address
  */
-export declare function getClientIP(headers: Record<string, string | string[] | undefined>, defaultIP?: string): string;
+export declare function getClientIP(headers: Headers, defaultIP?: string): string;