@anonympins/fingerprint 0.0.8 → 0.0.9

package/README.md

@@ -140,10 +140,10 @@ const securityConfig = {
         // Useful for internal tools, trusted partners, or monitoring services.
         // This check is performed first for maximum efficiency.
         { type: 'allowlist', entries: [
-            '192.168.1.100',      // A specific internal IP
-            '203.0.113.0/24',     // A partner's network range
-            '2001:db8::/32'       // An IPv6 range
-        ]},
+                '192.168.1.100',      // A specific internal IP
+                '203.0.113.0/24',     // A partner's network range
+                '2001:db8::/32'       // An IPv6 range
+            ]},
         // Option 2: DNS-verified bots (e.g., search engine crawlers).
         // This uses a secure DNS lookup (reverse then forward) to verify the bot's identity.
         // The result is cached per IP to avoid repeated DNS lookups.
@@ -198,17 +198,41 @@ The main Express middleware. It orchestrates identification, suspicion calculati
 
 #### `configureStore(store)`
 Allows replacing the in-memory store with an external datastore (like Redis) for persistence and scaling.
+The library provides ready-to-use adapters for popular datastores like Redis and MongoDB, which automatically handle the Time-To-Live (TTL) required for temporary data like challenge secrets.
 
-See the Datastore Integration Guide for a complete example of creating a Redis store.
+**Redis Example:**
 
 ```javascript
 import { configureStore } from './fingerprint.js';
-import { createRedisStore } from './redis-store.js'; // Assuming a redis store implementation exists
+import { createRedisStore } from './redis-store.js';
+import Redis from 'ioredis';
 
-const redisStore = createRedisStore(process.env.REDIS_URL);
+const redisClient = new Redis(process.env.REDIS_URL);
+const redisStore = createRedisStore(redisClient);
 configureStore(redisStore);
 ```
 
+**MongoDB Example:**
+
+```javascript
+import { configureStore } from './fingerprint.js';
+import { createMongoDbStore } from './mongodb-store.js';
+import { MongoClient } from 'mongodb';
+
+const mongoClient = new MongoClient(process.env.MONGODB_URL);
+
+// It's recommended to connect before your application starts listening.
+await mongoClient.connect(); 
+
+const mongoStore = createMongoDbStore(mongoClient.db('your-db-name'), 'sessions'); // 'sessions' is the collection name
+configureStore(mongoStore);
+
+// IMPORTANT: For automatic expiration of challenges and other temporary data to work,
+// you must create a TTL index on the `expiresAt` field in your MongoDB collection.
+// Run this command in the mongo shell:
+// db.sessions.createIndex({ "expiresAt": 1 }, { expireAfterSeconds: 0 })
+```
+
 #### `identifyRequest(req, res)`
 An asynchronous function that returns an identification string for a given request, based on its suspicion level (`device:<id>`, `suspicious_medium:<ip>`, etc.). Useful for integration with a custom rate-limiter.
 
@@ -300,34 +324,31 @@ To simplify setup, all client-side features can be enabled and configured throug
 
 ```javascript
 import { initializeClient } from './path/to/fingerprint.client.js';
-
-// --- EXAMPLES ---
-
-// Example 1: Enable all default protections and protect same-origin fetch requests.
+ 
+/**
+ * Initializes all client-side protections.
+ * This is the recommended way to set up the client-side library.
+ */
 initializeClient({
-  honeypots: ['email_confirm', 'user_nickname'], // Your honeypot field names
-  fetch: {} // An empty object enables fetch protection for same-origin
-});
-
-// Example 2: Enable everything and protect a specific API domain.
-initializeClient({
-  honeypots: ['email_confirm'],
+  // (Optional, default: true) Enable mouse movement tracking to detect non-human patterns.
+  // Set to `false` to disable.
+  mouse: true,
+ 
+  // (Optional, default: true) Enable keystroke dynamics tracking (timing between key presses).
+  // Set to `false` to disable.
+  keystrokes: true,
+ 
+  // (Optional) An array of `name` attributes for hidden form fields that act as bot traps.
+  honeypots: ['email_confirm', 'user_nickname', 'website_url'],
+ 
+  // (Optional) Enables automatic protection for `fetch` requests.
+  // If the `fetch` object is present, the protection is active.
   fetch: {
-    targetDomains: ['api.yourdomain.com']
+    // (Optional) An array of domains to protect. If empty or not provided,
+    // it protects same-origin requests by default.
+    targetDomains: ['api.yourdomain.com', 'auth.yourdomain.com']
   }
 });
-
-// Example 3: Enable only mouse and keystroke tracking, without patching fetch.
-initializeClient({
-  mouse: true,
-  keystrokes: true
-});
-
-// Example 4: Disable keystroke tracking but keep other defaults.
-initializeClient({
-  keystrokes: false,
-  fetch: {}
-});
 ```
 
 ### Client-Side Behavioral Analysis
@@ -352,15 +373,15 @@ This provides a proactive, first-line defense against simple bots. By setting up
 If you prefer not to modify global functions or need fine-grained control over which requests are protected, you can use the `protectedFetch` wrapper. You must use this function instead of the standard `fetch` for your API calls.
 
 - **`protectedFetch(resource, options)`**: A wrapper around the native `fetch` API that automatically enriches requests with security headers. It adds:
-  - `X-Device-Fingerprint`: The client's device fingerprint.
-  - `X-Behavior-Metrics`: A JSON string containing the metrics collected by the behavioral trackers (e.g., mouse entropy, honeypot interaction).
+    - `X-Device-Fingerprint`: The client's device fingerprint.
+    - `X-Behavior-Metrics`: A JSON string containing the metrics collected by the behavioral trackers (e.g., mouse entropy, honeypot interaction).
 
 **Example:**
 
 ```javascript
-import { 
-  initializeClient,
-  protectedFetch 
+import {
+    initializeClient,
+    protectedFetch
 } from './path/to/fingerprint.client.js';
 
 // Start tracking user behavior as soon as the app loads.

package/fingerprint.builder.js

@@ -0,0 +1,104 @@
+/**
+ * Algorithme de hachage cyrb53 (rapide et faible taux de collision).
+ */
+export const cyrb53 = (str, seed = 0) => {
+    let h1 = 0xdeadbeef ^ seed,
+        h2 = 0x41c6ce57 ^ seed;
+    for (let i = 0, ch; i < str.length; i++) {
+        ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 =
+        Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^
+        Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 =
+        Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^
+        Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+};
+
+/**
+ * Classe pour construire une empreinte composite (Multi-Hash).
+ * Format de sortie : "grp1:hash1|grp2:hash2|grp3:hash3"
+ */
+export class FingerprintBuilder {
+    constructor() {
+        this.components = new Map();
+    }
+
+    /**
+     * Ajoute un composant au hash global.
+     * @param {string} group - Le nom du groupe (ex: 'hw', 'screen', 'geo')
+     * @param {string|number|boolean} value - La valeur brute à hasher
+     */
+    add(group, value) {
+        if (value === undefined || value === null) return this;
+        // On hash la valeur individuellement pour l'anonymiser et réduire sa taille
+        this.components.set(group, cyrb53(String(value)));
+        return this;
+    }
+
+    /**
+     * Adds a raw component without hashing it.
+     * Useful for metrics that need to be read on the server.
+     * @param {string} group - The name of the group.
+     * @param {string|number} value - The raw value.
+     */
+    addRaw(group, value) {
+        if (value === undefined || value === null) return this;
+        this.components.set(group, value);
+        return this;
+    }
+    /**
+     * Génère la chaîne de signature finale.
+     * Trie les clés pour garantir un ordre déterministe.
+     */
+    toString() {
+        return Array.from(this.components.entries())
+            .sort((a, b) => a[0].localeCompare(b[0])) // Tri alphabétique des clés
+            .map(([key, hash]) => `${key}:${hash}`)
+            .join("|");
+    }
+
+    /**
+     * Compares two fingerprints and returns a similarity score (0 to 1).
+     * Uses weights to give more importance to strong invariants (Canvas, GPU).
+     * @param {string} fpString1 - Fingerprint A
+     * @param {string} fpString2 - Fingerprint B
+     */
+    static compare(fpString1, fpString2) {
+        if (!fpString1 || !fpString2) return 0;
+
+        const parse = (str) => new Map(str.split("|").map(part => part.split(":")).filter(([k,v]) => k && v));
+
+        const map1 = parse(fpString1);
+        const map2 = parse(fpString2);
+
+        // Poids de "véracité" (Entropie/Stabilité)
+        const weights = {
+            cvs: 4.0,   // Canvas: Très haute entropie (Rendu unique)
+            gpu: 3.0,   // GPU: Haute entropie (Matériel spécifique)
+            hw: 1.5,    // Hardware: Moyenne entropie
+            scr: 1.0,   // Screen: Moyenne
+            geo: 0.5,   // Geo: Faible (VPN/Voyage)
+            os: 0.5,    // OS: Faible (Générique)
+            bot: 0.0,   // Bot: Informatif
+        };
+
+        let weightedMatches = 0;
+        let totalWeight = 0;
+
+        const allKeys = new Set([...map1.keys(), ...map2.keys()]);
+
+        allKeys.forEach((key) => {
+            const weight = weights[key] || 1.0;
+            totalWeight += weight;
+            if (map1.get(key) === map2.get(key)) {
+                weightedMatches += weight;
+            }
+        });
+
+        return totalWeight === 0 ? 0 : weightedMatches / totalWeight;
+    }
+}

package/fingerprint.js

@@ -1,9 +1,11 @@
 // C:/Dev/games.primals.net/src/utils/fingerprint.js
 import crypto from "node:crypto";
-import { parse } from "node:net";
+import { BlockList } from "node:net";
 import dns from "node:dns/promises";
 import { Optimization } from "./library.js";
 import { cyrb53, FingerprintBuilder } from "./fingerprint.builder.js";
+export { createRedisStore } from "./redis-store.js";
+export { createMongoDbStore } from "./mongodb-store.js";
 
 /**
  * Retrieves the POW_SECRET from environment variables with appropriate checks.
@@ -702,7 +704,7 @@ function verifyTrapUrl(path, signature, nonce) {
 /**
  * @typedef {object} IStore
  * @property {(key: string) => Promise<any>} get
- * @property {(key: string, value: any) => Promise<void>} set
+ * @property {(key: string, value: any, ttl?: number) => Promise<void>} set
  * @property {(key: string) => Promise<boolean>} has
  * @property {(key: string) => Promise<void>} delete
  */
@@ -713,8 +715,21 @@ function verifyTrapUrl(path, signature, nonce) {
  */
 const inMemoryStore = {
   _map: new Map(),
+  _timeouts: new Map(),
   async get(key) { return this._map.get(key); },
-  async set(key, value) { this._map.set(key, value); },
+  async set(key, value, ttl) {
+    this._map.set(key, value);
+    // If a timeout already exists for this key, clear it.
+    if (this._timeouts.has(key)) {
+        clearTimeout(this._timeouts.get(key));
+        this._timeouts.delete(key);
+    }
+    // If a TTL is provided, set a timeout to delete the key.
+    if (ttl && ttl > 0) {
+        const timeoutId = setTimeout(() => this._map.delete(key), ttl * 1000);
+        this._timeouts.set(key, timeoutId);
+    }
+  },
   async has(key) { return this._map.has(key); },
   async delete(key) { this._map.delete(key); },
 };
@@ -861,7 +876,7 @@ export const getSuspicionVector = async (context, securityConfig) => {
     context._newCookies = context._newCookies || [];
     context._newCookies.push(newCookie);
   }
-  await store.set(`ip-device:${clientIp}`, deviceId); // Link the IP to the device
+  await store.set(`ip-device:${clientIp}`, deviceId, 600); // Link the IP to the device for 10 minutes
 
   // Periodically clean up device data
   if (Date.now() - deviceData.lastUpdate > 10 * 60 * 1000) { // 10 minutes
@@ -1084,14 +1099,16 @@ function generateCombinedPoWChallengePage(cpuChallengeDetails, memoryDifficulty,
  * Verifies a PoW solution based on a target and generates a ticket.
  */
 export function verifyCpuTargetPoWAndGenerateTicket(
-  clientIp,
+  clientIp, // This parameter is crucial and must be the actual client IP
   nonce,
   solution,
   suspicionFactor,
   clientSecret, // Le secret est maintenant requis
 ) {
   const target = calculateTarget(suspicionFactor);
-  const message = clientSecret ? `${clientIp}:${nonce}:${solution}:${clientSecret}` : `${clientIp}:${nonce}:${solution}`;
+  const message = clientSecret
+    ? `${clientIp}:${nonce}:${solution}:${clientSecret}`
+    : `${clientIp}:${nonce}:${solution}`;
   const hash = crypto
     .createHash("sha256")
     .update(message)
@@ -1124,6 +1141,7 @@ export class FingerprintEngine {
     const isProduction = process.env.NODE_ENV === 'production';
     this.securityConfig = securityConfig;
     this.isProduction = isProduction;
+    this._allowlist = this._buildAllowlist();
   }
 
   /**
@@ -1133,50 +1151,31 @@ export class FingerprintEngine {
    * @param {string} clientIp - The IP address of the client.
    * @returns {boolean} True if the IP is in the allowlist.
    */
-  _isIpInAllowlist(clientIp) {
+  _buildAllowlist() {
+    const blockList = new BlockList();
     const { whitelist = [] } = this.securityConfig;
     const allowlistRule = whitelist.find(rule => rule.type === 'allowlist');
 
     if (!allowlistRule || !allowlistRule.entries || allowlistRule.entries.length === 0) {
-      return false;
+      return blockList; // Retourne une liste vide
     }
 
-    const ip = parse(clientIp);
-    const ipVersion = ip.family;
-
     for (const entry of allowlistRule.entries) {
       if (entry.includes('/')) { // CIDR range
         try {
-          const [range, prefixStr] = entry.split('/');
-          const prefix = parseInt(prefixStr, 10);
-          const rangeIp = parse(range);
-
-          if (rangeIp.family !== ipVersion) continue;
-
-          const ipBytes = ip.toBuffer();
-          const rangeBytes = rangeIp.toBuffer();
-          const mask = Buffer.alloc(ipBytes.length, 0xff);
-
-          for (let i = 0; i < Math.floor(prefix / 8); i++) {
-            if (ipBytes[i] !== rangeBytes[i]) {
-              break; // Mismatch in full byte, move to next entry
-            }
-          }
-          const remainingBits = prefix % 8;
-          if (remainingBits > 0) {
-            const byteIndex = Math.floor(prefix / 8);
-            const bitmask = (0xff << (8 - remainingBits)) & 0xff;
-            if ((ipBytes[byteIndex] & bitmask) !== (rangeBytes[byteIndex] & bitmask)) {
-              continue; // Mismatch in partial byte
-            }
-          }
-          return true; // IP is in CIDR range
-        } catch (e) { continue; /* Ignore invalid CIDR entries */ }
-      } else if (entry === clientIp) { // Direct IP match
-        return true;
+          const [address, prefix] = entry.split('/');
+          blockList.addSubnet(address, parseInt(prefix, 10));
+        } catch (e) {
+          // Ignore les entrées CIDR invalides
+        }
+      } else { // Direct IP match
+        blockList.addAddress(entry);
       }
     }
-    return false;
+    return blockList;
+  }
+  _isIpInAllowlist(clientIp) {
+    return this._allowlist.check(clientIp);
   }
   /**
    * Verifies if a request comes from a legitimate, whitelisted bot (e.g., Googlebot)
@@ -1224,26 +1223,26 @@ export class FingerprintEngine {
       const validHostname = hostnames.find(h => h.endsWith(matchedRule.hostnameSuffix));
 
       if (!validHostname) {
-        await store.set(cacheKey, 'failed', 86400); // Cache failure for 24h
+        await store.set(cacheKey, 'failed', 86400); // Cache failure for 24h (TTL in seconds)
         return false;
       }
 
       // 2. Forward DNS lookup
       const addresses = await dns.resolve(validHostname);
       if (addresses.includes(clientIp)) {
-        await store.set(cacheKey, 'verified', 86400); // Cache success for 24h
+        await store.set(cacheKey, 'verified', 86400); // Cache success for 24h (TTL in seconds)
         return true;
       }
     } catch (error) {
       // DNS errors are common (e.g., for IPs with no rDNS record), treat as failure.
     }
 
-    await store.set(cacheKey, 'failed', 86400); // Cache failure for 24h
+    await store.set(cacheKey, 'failed', 86400); // Cache failure for 24h (TTL in seconds)
     return false;
   }
 
   async processRequest(requestContext) {
-    const { clientIp, path, cookies, query, isStatic } = requestContext;
+    const { clientIp = "unknown", path, cookies, query, isStatic } = requestContext;
     const { weights, thresholds, logger, onDeviceCompromised } = this.securityConfig;
     if (isStatic) {
       return { action: 'next', score: 0, vector: {} };
@@ -1350,7 +1349,7 @@ export class FingerprintEngine {
         if (logger) {
             logger({ type: 'trap_triggered', deviceId: cookies?.device_id, score: 100, path: path, timestamp: Date.now() });
         }
-        await store.set(`device:${cookies.device_id}`, deviceData);
+        await store.set(`device:${cookies.device_id}`, deviceData); // No TTL for condemned status
         return { action: 'block', status: 403, body: 'Forbidden', score: 100, vector: { honeypotScore: 100 } };
     }
 
@@ -1436,7 +1435,7 @@ export class FingerprintEngine {
 
         // Associate the current challenge nonce with the device for trap URL verification later.
         if (deviceData) {
-            deviceData.lastChallengeNonce = nonce;
+            deviceData.lastChallengeNonce = nonce; // No TTL, part of the main device object
             await store.set(`device:${cookies.device_id}`, deviceData);
         }
 
@@ -1512,7 +1511,7 @@ export class FingerprintEngine {
     if (ipProfile.statelessCount > statelessLimit) {
       return `suspicious_high:${clientIp}`;
     }
-    await store.set(`ip:${clientIp}`, ipProfile);
+    await store.set(`ip:${clientIp}`, ipProfile, 600); // Keep IP profile for 10 minutes
 
     const vector = await __internal.getSuspicionVector(requestContext, this.securityConfig); // Pass the config
     const { honeypotScore } = getHoneypotScore(requestContext, this.securityConfig.honeypot);

package/mongodb-store.js

@@ -0,0 +1,53 @@
+/**
+ * @file Creates a store adapter for MongoDB.
+ * This adapter uses a collection as a key-value store and leverages MongoDB's TTL indexes
+ * for automatic expiration of documents.
+ */
+
+/**
+ * Creates a store adapter for a MongoDB collection.
+ * It's recommended to pass the `db` object and let the adapter handle the collection.
+ *
+ * **Note:** For TTL to work, you must create a TTL index on the `expiresAt` field in your collection.
+ * In the mongo shell, run:
+ * `db.yourCollectionName.createIndex({ "expiresAt": 1 }, { expireAfterSeconds: 0 })`
+ *
+ * @param {import('mongodb').Db} db - An instance of a MongoDB Db object.
+ * @param {string} [collectionName='fingerprint_store'] - The name of the collection to use.
+ * @returns {import('./fingerprint.js').IStore} An object that complies with the IStore interface.
+ */
+export function createMongoDbStore(db, collectionName = 'fingerprint_store') {
+  const collection = db.collection(collectionName);
+
+  return {
+    async get(key) {
+      const doc = await collection.findOne({ _id: key });
+      // The TTL index automatically removes expired documents, so no need to check `expiresAt` here.
+      return doc ? doc.value : null;
+    },
+    async set(key, value, ttl) {
+      const doc = {
+        _id: key,
+        value: value,
+      };
+
+      if (ttl && ttl > 0) {
+        // Set the expiration date for the TTL index.
+        doc.expiresAt = new Date(Date.now() + ttl * 1000);
+      }
+
+      await collection.updateOne(
+        { _id: key },
+        { $set: doc },
+        { upsert: true }
+      );
+    },
+    async has(key) {
+      const count = await collection.countDocuments({ _id: key });
+      return count > 0;
+    },
+    async delete(key) {
+      await collection.deleteOne({ _id: key });
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anonympins/fingerprint",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "An HTTP(S) client mitigation and anti-bot protection library for Node.js/Express, based on digital fingerprinting and dynamic Proof-of-Work (PoW) challenges.",
   "main": "fingerprint.js",
   "type": "module",
@@ -13,7 +13,11 @@
   "files": [
     "fingerprint.js",
     "fingerprint.client.js",
+    "fingerprint.builder.js",
     "library.js",
+    "redis-store.js",
+    "mongodb-store.js",
+    "sql-store.js",
     "README.md",
     "LICENSE"
   ],
@@ -45,17 +49,27 @@
     "body-parser": "^1.20.2",
     "cookie-parser": "^1.4.6",
     "express": "^4.18.2",
-    "vitest": "^4.1.11",
-    "ioredis": "^5.3.2",
-    "mongodb": "^6.3.0",
-    "prom-client": "^15.1.2"
+    "prom-client": "^15.1.2",
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "ioredis": "^5.3.2",
-    "mongodb": "^6.3.0"
+    "knex": ">=3.0.0",
+    "mongodb": "^6.3.0",
+    "sqlite3": "^5.1.7"
   },
   "peerDependenciesMeta": {
-    "ioredis": { "optional": true },
-    "mongodb": { "optional": true }
+    "ioredis": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "knex": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    }
   }
 }

package/redis-store.js

@@ -0,0 +1,43 @@
+/**
+ * @file Creates a store adapter for ioredis.
+ * This adapter handles the serialization and deserialization of complex objects,
+ * including the conversion of Set objects to arrays for storage in Redis.
+ */
+
+/**
+ * Creates a store adapter for an ioredis client.
+ * @param {import('ioredis').Redis} redisClient - An instance of the ioredis client.
+ * @returns {import('./fingerprint.js').IStore} An object that complies with the IStore interface.
+ */
+export function createRedisStore(redisClient) {
+  return {
+    async get(key) {
+      const value = await redisClient.get(key);
+      if (!value) return null;
+      // Use a reviver to convert arrays back to Sets for specific keys like 'ips'.
+      return JSON.parse(value, (k, v) => {
+        if (k === 'ips' && Array.isArray(v)) {
+          return new Set(v);
+        }
+        return v;
+      });
+    },
+    async set(key, value, ttl) {
+      // Use a replacer to convert Set objects into arrays before serialization.
+      const stringValue = JSON.stringify(value, (k, v) => {
+        if (v instanceof Set) {
+          return Array.from(v);
+        }
+        return v;
+      });
+
+      if (ttl && ttl > 0) {
+        await redisClient.set(key, stringValue, 'EX', ttl);
+      } else {
+        await redisClient.set(key, stringValue);
+      }
+    },
+    async has(key) { return (await redisClient.exists(key)) === 1; },
+    async delete(key) { await redisClient.del(key); },
+  };
+}

package/sql-store.js

@@ -0,0 +1,78 @@
+/**
+ * @file Creates a store adapter for Knex.js.
+ * This adapter is compatible with various SQL databases like PostgreSQL, MySQL, and SQLite.
+ * It handles serialization of complex objects and TTL for automatic data expiration.
+ */
+
+/**
+ * Creates a store adapter for a Knex.js client.
+ *
+ * **Note:** You must create the table yourself before using the store.
+ * The table should have at least the following columns:
+ * - `key` (string, primary key)
+ * - `value` (text or json/jsonb)
+ * - `expiresAt` (datetime or timestamp with time zone)
+ *
+ * Example schema for PostgreSQL:
+ * ```sql
+ * CREATE TABLE your_table_name (
+ *   "key" VARCHAR(255) PRIMARY KEY,
+ *   "value" TEXT NOT NULL,
+ *   "expiresAt" TIMESTAMPTZ
+ * );
+ * ```
+ *
+ * @param {import('knex').Knex} knex - An instance of the Knex client.
+ * @param {string} [tableName='fingerprint_store'] - The name of the table to use.
+ * @returns {import('./fingerprint.js').IStore} An object that complies with the IStore interface.
+ */
+export function createSqlStore(knex, tableName = 'fingerprint_store') {
+  // Custom replacer/reviver to handle Set serialization, similar to the Redis store.
+  const replacer = (k, v) => (v instanceof Set ? Array.from(v) : v);
+  const reviver = (k, v) => (k === 'ips' && Array.isArray(v) ? new Set(v) : v);
+
+  return {
+    async get(key) {
+      const row = await knex(tableName).where('key', key).first();
+      if (!row) return null;
+
+      // Manually check for expiration, as not all SQL databases have automatic TTL cleanup.
+      if (row.expiresAt && new Date(row.expiresAt) < new Date()) {
+        await this.delete(key); // Clean up expired key.
+        return null;
+      }
+
+      try {
+        return JSON.parse(row.value, reviver);
+      } catch (e) {
+        // In case of malformed JSON, treat it as a miss.
+        return null;
+      }
+    },
+
+    async set(key, value, ttl) {
+      const stringValue = JSON.stringify(value, replacer);
+      const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
+
+      // Use native upsert capabilities of Knex for different SQL dialects.
+      await knex(tableName)
+        .insert({ key, value: stringValue, expiresAt })
+        .onConflict('key')
+        .merge();
+    },
+
+    async has(key) {
+      const row = await knex(tableName).where('key', key).first('key');
+      if (!row) return false;
+      // Also check for expiration here.
+      if (row.expiresAt && new Date(row.expiresAt) < new Date()) {
+        return false;
+      }
+      return true;
+    },
+
+    async delete(key) {
+      await knex(tableName).where('key', key).del();
+    },
+  };
+}