bot-shield 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# BotShield Middleware
+
+An Economic Deterrence Bot Mitigation Middleware for Express/Node.js based on V8 Javascript cryptographic token challenges. 
+
+This package protects your valuable API endpoints by filtering out automated scrapers and bots trying to steal data, while allowing legitimate human browsers to seamlessly access the content.
+
+## Installation
+
+```bash
+npm install bot-shield-mca
+```
+
+## Basic Usage
+
+```javascript
+const express = require('express');
+const BotShield = require('bot-shield-mca');
+
+const app = express();
+const botShield = new BotShield({
+    riskThreshold: 70,              // Blocking threshold (default 70)
+    maxRequestsPerWindow: 50,       // Rate limiting volume
+    minTimeBetweenRequestsMs: 200   // Velocity tracking
+});
+
+// 1. Expose the challenge token endpoint
+app.get('/api/bot-challenge', botShield.challengeEndpoint);
+
+// 2. Protect your valuable data API with the middleware
+app.get('/api/data', botShield.protectApi, (req, res) => {
+    res.json({ message: "Protected data payload!" });
+});
+
+app.listen(3000);
+```
+
+## Frontend Integration (The X-BOT-SIGNAL)
+
+Legitimate browsers must solve the execution challenge to retrieve the token and present it in the headers (`X-shield-token`) to access the protected JSON payload.
+
+```javascript
+// Step 1: Challenge
+const challenge = await fetch('http://localhost:3000/api/bot-challenge');
+const { token } = await challenge.json();
+
+// Step 2: Retrieve protected data
+const response = await fetch('http://localhost:3000/api/data', {
+    headers: {
+        'x-shield-token': token
+    }
+});
+const data = await response.json();
+```

package/index.js

@@ -0,0 +1,94 @@
+const crypto = require('crypto');
+
+class BotShield {
+    constructor(options = {}) {
+        this.riskThreshold = options.riskThreshold || 70;
+        this.timeWindowMs = options.timeWindowMs || 60000; 
+        this.maxRequestsPerWindow = options.maxRequestsPerWindow || 50;
+        this.minTimeBetweenRequestsMs = options.minTimeBetweenRequestsMs || 200; 
+        
+        this.clients = new Map();
+        this.validTokens = new Set();
+    }
+
+    challengeEndpoint = (req, res) => {
+        const token = crypto.randomBytes(16).toString('hex');
+        this.validTokens.add(token);
+        setTimeout(() => this.validTokens.delete(token), 5 * 60 * 1000);
+        res.json({ token });
+    };
+
+    _getClientData(ip) {
+        if (!this.clients.has(ip)) {
+            this.clients.set(ip, {
+                requestCount: 0,
+                lastRequestTime: Date.now(),
+                firstRequestTime: Date.now()
+            });
+        }
+        return this.clients.get(ip);
+    }
+
+    _calculateRiskScore(clientData, hasValidToken, timeSinceLastRequest) {
+        let score = 0;
+        const signals = {};
+
+        if (!hasValidToken) {
+            score += 75; 
+            signals.jsExecuted = false;
+        } else {
+            signals.jsExecuted = true;
+        }
+
+        if (timeSinceLastRequest < this.minTimeBetweenRequestsMs) {
+            score += 30;
+            signals.suspiciousTiming = true;
+        }
+
+        if (clientData.requestCount > this.maxRequestsPerWindow) {
+            score += 40;
+            signals.highVolume = true;
+        }
+
+        return { score, signals };
+    }
+
+    protectApi = (req, res, next) => {
+        const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
+        const clientToken = req.headers['x-shield-token'];
+        const now = Date.now();
+
+        const clientData = this._getClientData(ip);
+        const timeSinceLastRequest = now - clientData.lastRequestTime;
+        const hasValidToken = this.validTokens.has(clientToken);
+
+        if (now - clientData.firstRequestTime > this.timeWindowMs) {
+            clientData.requestCount = 0;
+            clientData.firstRequestTime = now;
+        }
+
+        clientData.requestCount += 1;
+        clientData.lastRequestTime = now;
+
+        const { score, signals } = this._calculateRiskScore(clientData, hasValidToken, timeSinceLastRequest);
+
+        if (score >= this.riskThreshold) {
+            console.log("\n" + "X".repeat(60));
+            console.log("🚨 [THREAT INTERCEPTED] 🚨");
+            console.log(`[!] Target: ${req.originalUrl} | IP: ${ip} | Risk Score: ${score}/100`);
+            console.log(`[!] Primary Reason: X-BOT-SIGNAL Missing`);
+            console.log("X".repeat(60));
+
+            return res.status(403).json({
+                error: "Access Denied",
+                code: "SHIELD_ERR",
+                message: "Verification Required. Unverified client behavior detected."
+            });
+        }
+
+        this.clients.set(ip, clientData);
+        next();
+    };
+}
+
+module.exports = BotShield;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "bot-shield",
+  "version": "1.0.0",
+  "description": "An Economic Deterrence Bot Mitigation Middleware for Express",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "bot-protection",
+    "middleware",
+    "express",
+    "security",
+    "bot-shield",
+    "rate-limiting",
+    "economic-deterrence"
+  ],
+  "author": "Your Name",
+  "license": "ISC"
+}