@anonympins/fingerprint 0.0.8 → 0.1.0

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.1.0",
   "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",
@@ -8,12 +8,16 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run --reporter=verbose"
   },
   "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();
+    },
+  };
+}