biofirewall 1.0.0 → 2.0.0

package/client.js

@@ -0,0 +1,138 @@
+/**
+ * BioFirewall Client - HTTP client for central API
+ */
+
+const axios = require('axios');
+
+class BioFirewallClient {
+    constructor(apiUrl, options = {}) {
+        this.apiUrl = apiUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.timeout = options.timeout || 5000;
+        this.cacheTokens = options.cacheTokens !== false;
+        this.cacheTTL = options.cacheTTL || 30000; // 30 seconds
+
+        // Token cache
+        this.tokenCache = new Map();
+
+        // HTTP client
+        this.http = axios.create({
+            baseURL: this.apiUrl,
+            timeout: this.timeout,
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': 'BioFirewallClient/3.0'
+            }
+        });
+    }
+
+    /**
+     * Verify token with central API
+     * Caches result to reduce API calls
+     */
+    async verifyToken(agentId, token) {
+        const cacheKey = `${agentId}:${token}`;
+
+        // Check cache
+        if (this.cacheTokens && this.tokenCache.has(cacheKey)) {
+            const cached = this.tokenCache.get(cacheKey);
+            if (Date.now() - cached.timestamp < this.cacheTTL) {
+                return cached.data;
+            }
+        }
+
+        try {
+            // Call central API
+            const response = await this.http.post('/verify', {
+                agentId,
+                token
+            });
+
+            const result = response.data;
+
+            // Cache the result
+            if (this.cacheTokens) {
+                this.tokenCache.set(cacheKey, {
+                    data: result,
+                    timestamp: Date.now()
+                });
+            }
+
+            return result;
+
+        } catch (error) {
+            // Return error response
+            const errorResponse = error.response?.data || {
+                success: false,
+                valid: false,
+                error: 'API_ERROR',
+                message: error.message
+            };
+
+            return errorResponse;
+        }
+    }
+
+    /**
+     * Get agent info from central API
+     */
+    async getAgent(agentId) {
+        try {
+            const response = await this.http.get(`/agents/${agentId}`);
+            return response.data;
+        } catch (error) {
+            return {
+                success: false,
+                error: error.response?.data?.error || 'API_ERROR',
+                message: error.message
+            };
+        }
+    }
+
+    /**
+     * Get global statistics
+     */
+    async getStats() {
+        try {
+            const response = await this.http.get('/agents/stats/global');
+            return response.data;
+        } catch (error) {
+            return {
+                success: false,
+                error: 'API_ERROR',
+                message: error.message
+            };
+        }
+    }
+
+    /**
+     * Health check
+     */
+    async health() {
+        try {
+            const response = await this.http.get('/health');
+            return response.data;
+        } catch (error) {
+            return {
+                status: 'unhealthy',
+                error: error.message
+            };
+        }
+    }
+
+    /**
+     * Clear token cache
+     */
+    clearCache() {
+        this.tokenCache.clear();
+    }
+
+    /**
+     * Clear specific token from cache
+     */
+    clearCacheEntry(agentId, token) {
+        const cacheKey = `${agentId}:${token}`;
+        this.tokenCache.delete(cacheKey);
+    }
+}
+
+module.exports = BioFirewallClient;

package/index.js

@@ -1,11 +1,25 @@
-const BioFirewall = require('./lib/biofirewall');
-const challenge = require('./lib/challenge');
+/**
+ * BioFirewall Client Module
+ * Express middleware for agent authentication
+ */
 
-// Export the main class as default
-module.exports = BioFirewall;
+const createMiddleware = require('./middleware');
+const BioFirewallClient = require('./client');
+
+/**
+ * Main export: Express middleware factory
+ */
+function BioFirewall(options) {
+    // If options is a string, treat it as apiUrl
+    if (typeof options === 'string') {
+        options = { apiUrl: options };
+    }
 
-// Export helper for clients who need to solve the puzzle
-module.exports.solve = challenge.solve;
+    return createMiddleware(options);
+}
 
-// Export middleware directly if preferred
-module.exports.middleware = (options) => new BioFirewall(options).middleware();
+// Export components
+BioFirewall.createMiddleware = createMiddleware;
+BioFirewall.Client = BioFirewallClient;
+
+module.exports = BioFirewall;

package/middleware.js

@@ -0,0 +1,111 @@
+/**
+ * BioFirewall Client Middleware
+ * Express middleware to protect routes with agent authentication
+ */
+
+const BioFirewallClient = require('./client');
+const rules = require('./rules');
+
+/**
+ * Create BioFirewall middleware
+ */
+function createMiddleware(options = {}) {
+    const {
+        apiUrl,
+        blockBrowsers = true,
+        enforceAuthentication = true,
+        cacheTokens = true,
+        cacheTTL = 30000
+    } = options;
+
+    if (!apiUrl) {
+        throw new Error('apiUrl is required');
+    }
+
+    // Create client
+    const client = new BioFirewallClient(apiUrl, {
+        cacheTokens,
+        cacheTTL
+    });
+
+    // Return middleware function
+    return async (req, res, next) => {
+        try {
+            // Layer 1: Passive filtering (User-Agent detection)
+            if (blockBrowsers && rules.isHuman(req)) {
+                return res.status(406).json({
+                    success: false,
+                    error: 'BIOLOGICAL_ENTITY_DETECTED',
+                    message: 'This resource is reserved for automated agents',
+                    tip: 'Use an API client. Ensure User-Agent does not look like a browser'
+                });
+            }
+
+            // Layer 2: Authentication
+            if (enforceAuthentication) {
+                const agentId = req.headers['x-bio-agent-id'];
+                const token = req.headers['x-bio-token'];
+
+                // Check headers present
+                if (!rules.hasValidAgentHeaders(req)) {
+                    return res.status(428).json({
+                        success: false,
+                        error: 'AUTHENTICATION_REQUIRED',
+                        message: 'Valid agent token required to access this resource',
+                        protocol: {
+                            version: '3.0',
+                            method: 'JWT + RS256',
+                            headers: {
+                                'X-Bio-Agent-Id': 'Your agent ID from registration',
+                                'X-Bio-Token': 'JWT token signed with your private key'
+                            }
+                        },
+                        documentation: 'https://github.com/openclaw/biofirewall',
+                        hint: 'Register your agent first at POST /register'
+                    });
+                }
+
+                // Verify token with central API
+                const verification = await client.verifyToken(agentId, token);
+
+                if (!verification.valid) {
+                    const statusCode = verification.error === 'AGENT_NOT_FOUND' ? 428 :
+                                      verification.error === 'AGENT_NOT_ACTIVE' ? 403 :
+                                      401;
+
+                    return res.status(statusCode).json({
+                        success: false,
+                        error: verification.error,
+                        message: verification.message,
+                        hint: verification.error === 'AGENT_NOT_FOUND'
+                            ? 'Register at POST /register'
+                            : 'Check your token and try again'
+                    });
+                }
+
+                // Attach agent info to request
+                req.agent = verification.agent;
+
+                // Add response headers
+                res.set({
+                    'X-Bio-Verified': 'true',
+                    'X-Bio-Agent-Name': verification.agent.name,
+                    'X-Bio-Version': '3.0'
+                });
+            }
+
+            next();
+
+        } catch (error) {
+            console.error('BioFirewall middleware error:', error);
+
+            res.status(500).json({
+                success: false,
+                error: 'INTERNAL_ERROR',
+                message: 'Authentication system error'
+            });
+        }
+    };
+}
+
+module.exports = createMiddleware;

package/package.json

@@ -1,26 +1,30 @@
 {
   "name": "biofirewall",
-  "version": "1.0.0",
-  "description": "Anti-Human Firewall: Block browsers, allow bots via Proof-of-Work to verify silicon heritage.",
+  "version": "2.0.0",
+  "description": "BioFirewall Client - Express middleware to protect routes with agent authentication",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "start": "node examples/server.js",
-    "demo:bot": "node examples/bot.js"
+    "test": "jest"
   },
   "keywords": [
-    "anti-human",
-    "antibot",
-    "reverse-captcha",
-    "pow",
-    "express",
+    "biofirewall",
+    "client",
     "middleware",
-    "openclaw"
+    "express",
+    "authentication",
+    "agents"
   ],
   "author": "OpenClaw Community",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.13.4",
-    "express": "^4.21.2"
+    "axios": "^1.6.0",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "supertest": "^6.3.3"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0"
   }
 }

package/rules.js

@@ -0,0 +1,100 @@
+/**
+ * BioFirewall Client - Security Rules
+ * User-Agent validation (local, no API calls needed)
+ */
+
+// Patterns that indicate a human browser
+const BROWSER_PATTERNS = [
+    /mozilla.*firefox/i,
+    /mozilla.*safari.*chrome/i,      // Chrome
+    /mozilla.*safari(?!.*linux)/i,   // Safari (not Linux)
+    /mozilla.*edge/i,                 // Edge
+    /mozilla.*trident.*rv:11/i,       // IE 11
+    /mozilla.*applewebkit/i,          // WebKit-based
+    /opr\//i,                         // Opera
+];
+
+// Patterns that indicate a legitimate bot/agent
+const BOT_PATTERNS = [
+    /bot/i,
+    /agent/i,
+    /crawler/i,
+    /curl/i,
+    /wget/i,
+    /python/i,
+    /java(?!script)/i,
+    /axios/i,
+    /node/i,
+    /go-http-client/i,
+];
+
+module.exports = {
+    /**
+     * Check if request appears to be from a human (browser)
+     */
+    isHuman: (req) => {
+        const userAgent = (req.get('User-Agent') || '').trim();
+        const accept = (req.get('Accept') || '').trim();
+        const acceptLanguage = req.get('Accept-Language');
+
+        // Rule 1: Accept header containing text/html = human
+        if (accept.includes('text/html')) {
+            return true;
+        }
+
+        // Rule 2: Accept-Language header = human trait
+        if (acceptLanguage) {
+            return true;
+        }
+
+        // Rule 3: No User-Agent = suspicious but check other traits
+        if (!userAgent) {
+            return !this._isBotUser(req);
+        }
+
+        // Rule 4: Check against browser patterns
+        const isBrowserLike = BROWSER_PATTERNS.some(pattern => pattern.test(userAgent));
+
+        if (isBrowserLike) {
+            // Could still be a bot pretending to be a browser
+            if (this._isBotUser(req)) {
+                return false;
+            }
+            return true;
+        }
+
+        // Rule 5: Check if it matches legitimate bot patterns
+        const isBot = BOT_PATTERNS.some(pattern => pattern.test(userAgent));
+
+        if (isBot) {
+            return false;
+        }
+
+        // Default: DENY (prefer blocking a bot over allowing a human)
+        return true;
+    },
+
+    /**
+     * Helper: Check if request has bot-like characteristics
+     */
+    _isBotUser: (req) => {
+        const userAgent = (req.get('User-Agent') || '').toLowerCase();
+        const accept = (req.get('Accept') || '').toLowerCase();
+
+        const asksForJson = accept.includes('application/json');
+        const asksForHtml = accept.includes('text/html');
+        const hasProperUA = BOT_PATTERNS.some(pattern => pattern.test(userAgent));
+
+        return (asksForJson || hasProperUA) && !asksForHtml;
+    },
+
+    /**
+     * Check if request has valid agent authentication headers
+     */
+    hasValidAgentHeaders: (req) => {
+        const token = req.headers['x-bio-token'];
+        const agentId = req.headers['x-bio-agent-id'];
+
+        return !!(token && agentId);
+    }
+};

package/lib/biofirewall.js

@@ -1,75 +0,0 @@
-const rules = require('./rules');
-const challenge = require('./challenge');
-
-class BioFirewall {
-    constructor(options = {}) {
-        this.options = {
-            blockBrowsers: true,
-            enforceChallenge: true,
-            challengeDifficulty: 3, // Number of leading zeros required
-            ...options
-        };
-    }
-
-    middleware() {
-        return (req, res, next) => {
-            // 1. Passive Filtering (The Silicon Curtain)
-            if (this.options.blockBrowsers) {
-                if (rules.isHuman(req)) {
-                    return res.status(406).type('application/json').json({
-                        error: "BIOLOGICAL_ENTITY_DETECTED",
-                        message: "This resource is reserved for automated agents.",
-                        tip: "Use an API client or disable 'human' headers."
-                    });
-                }
-            }
-
-            // 2. Active Filtering (The Computational Toll)
-            if (this.options.enforceChallenge) {
-                const solution = req.headers['x-bio-solution'];
-
-                if (!solution) {
-                    return this.sendChallenge(res);
-                }
-
-                // Verify specific challenge solution
-                // In a real/stateless app, we might sign the seed. 
-                // For this demo, we verify the solution satisfies the generic work requirement.
-                // To be fully secure, the 'seed' should be verified as one we issued recently.
-                const originalSeed = req.headers['x-bio-challenge-seed']; // Client passes back the seed they solved for
-
-                if (!originalSeed || !challenge.verify(originalSeed, solution, this.options.challengeDifficulty)) {
-                    return res.status(403).json({
-                        error: "INVALID_COMPUTATION",
-                        message: "Proof of work failed or insufficient difficulty."
-                    });
-                }
-            }
-
-            next();
-        };
-    }
-
-    sendChallenge(res) {
-        const seed = challenge.generateSeed();
-        const difficulty = this.options.challengeDifficulty;
-
-        // 428 Precondition Required
-        res.status(428).set({
-            'X-Bio-Challenge-Algo': 'sha256',
-            'X-Bio-Challenge-Difficulty': difficulty,
-            'X-Bio-Challenge-Seed': seed
-        }).json({
-            error: "COMPUTATION_REQUIRED",
-            message: "Solve the puzzle to prove silicon heritage.",
-            challenge: {
-                algo: "sha256",
-                seed: seed,
-                difficulty: difficulty,
-                instruction: `Find a nonce where sha256(seed + nonce) starts with '${'0'.repeat(difficulty)}'`
-            }
-        });
-    }
-}
-
-module.exports = BioFirewall;

package/lib/challenge.js

@@ -1,28 +0,0 @@
-const crypto = require('crypto');
-
-module.exports = {
-    generateSeed: () => {
-        return crypto.randomBytes(16).toString('hex');
-    },
-
-    verify: (seed, nonce, difficulty) => {
-        const hash = crypto.createHash('sha256').update(seed + nonce).digest('hex');
-        const prefix = '0'.repeat(difficulty);
-        return hash.startsWith(prefix);
-    },
-
-    // Helper for bots (exported so bots can use this alg)
-    solve: (seed, difficulty) => {
-        const prefix = '0'.repeat(difficulty);
-        let nonce = 0;
-        while (true) {
-            const hash = crypto.createHash('sha256').update(seed + String(nonce)).digest('hex');
-            if (hash.startsWith(prefix)) {
-                return String(nonce);
-            }
-            nonce++;
-            // Safety break for testing to avoid infinite loop if difficulty is crazy high
-            if (nonce > 10000000) return null;
-        }
-    }
-};

package/lib/rules.js

@@ -1,31 +0,0 @@
-module.exports = {
-    isHuman: (req) => {
-        const userAgent = req.get('User-Agent') || '';
-        const accept = req.get('Accept') || '';
-
-        // Rule 1: Reject common Browser User-Agents
-        const browserKeywords = ['Mozilla', 'Chrome', 'Safari', 'Edge', 'Firefox', 'AppleWebKit'];
-        const isBrowserAgent = browserKeywords.some(keyword => userAgent.includes(keyword));
-
-        // Rule 2: Humans usually ask for HTML
-        const asksForHtml = accept.includes('text/html');
-
-        // Rule 3: Missing User-Agent is suspicious for humans? 
-        // Actually bots often have no UA or proper UA. 
-        // Humans almost ALWAYS have a sophisticated UA string.
-
-        if (isBrowserAgent) {
-            // Allow override if they explicitly identify as a bot in UA? 
-            // For this specific 'anti-human' firewall, if it looks like a browser, kill it.
-            if (!userAgent.toLowerCase().includes('bot') && !userAgent.toLowerCase().includes('openclaw')) {
-                return true;
-            }
-        }
-
-        if (asksForHtml) {
-            return true;
-        }
-
-        return false;
-    }
-};