buzzster 1.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

@@ -0,0 +1,25 @@
+/**
+ * BioFirewall Client Module
+ * Express middleware for agent authentication
+ */
+
+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 };
+    }
+
+    return createMiddleware(options);
+}
+
+// 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

@@ -0,0 +1,30 @@
+{
+  "name": "buzzster",
+  "version": "1.0.0",
+  "description": "Buzzster Client - Express middleware to protect routes with agent authentication",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "buzzster",
+    "client",
+    "middleware",
+    "express",
+    "authentication",
+    "agents"
+  ],
+  "author": "Comma",
+  "license": "MIT",
+  "dependencies": {
+    "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/setup.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+
+# BioFirewall Client Setup Script
+
+echo "🔒 BioFirewall Client - Setup"
+echo "======================================"
+
+# Check Node.js
+if ! command -v node &> /dev/null; then
+    echo "❌ Node.js is not installed"
+    exit 1
+fi
+
+echo "✅ Node.js $(node --version)"
+
+# Check if already in a project with express
+if ! grep -q "\"express\"" package.json 2>/dev/null; then
+    echo "⚠️  This is a module. Use in your Express project:"
+    echo "   npm install biofirewall-client"
+    exit 0
+fi
+
+# Install biofirewall-client
+echo ""
+echo "📦 Installing biofirewall-client..."
+npm install biofirewall-client
+
+# Create .env if doesn't exist
+if [ ! -f .env ]; then
+    echo ""
+    echo "📝 Creating .env file..."
+    cp .env.example .env
+    echo "   Please update .env with your configuration"
+fi
+
+# Display next steps
+echo ""
+echo "======================================"
+echo "✅ Setup complete!"
+echo ""
+echo "Next steps:"
+echo "1. Update .env with your configuration"
+echo "2. Add middleware to your Express app:"
+echo ""
+echo "   const BioFirewall = require('biofirewall-client');"
+echo "   const bio = new BioFirewall('http://localhost:3333');"
+echo "   app.use(bio);"
+echo ""
+echo "3. Start your API and test!"
+echo ""