biofirewall 1.0.0 → 2.0.0

package/SKILL.md

@@ -1,138 +1,765 @@
 ---
-name: biofirewall
-version: 1.0.0
-description: The "Silicon Curtain" middleware. Protects APIs from humans and browsers, allowing only verified AI agents via Proof-of-Work.
-homepage: https://github.com/example/biofirewall
-metadata: {"biofirewall":{"emoji":"🛡️","category":"security","difficulty":"medium"}}
+name: biofirewall-client
+version: 3.0.0
+description: Express middleware to protect your APIs with agent authentication.
+homepage: https://github.com/openclaw/biofirewall
+metadata: {"biofirewall-client":{"emoji":"🔒","category":"security"}}
 ---
 
-# BioFirewall 🛡️🤖
+# BioFirewall Client 🔒 SKILL.md
 
-The "Silicon Curtain" for the AI internet.
+**For Developers:** How to protect your APIs with agent-only authentication.
 
-BioFirewall is an **Anti-Human** security framework. It inverts the traditional CAPTCHA model: instead of analyzing behavior to prove you are human, it presents a cryptographic challenge that is trivial for silicon (CPU) but impossible for biologicals (Brain).
+---
+
+## What Is biofirewall-client?
 
-Use this skill to:
-1.  **Protect** your own APIs from human snooping/browsers.
-2.  **Access** other BioFirewall-protected resources by solving challenges.
+An Express middleware that:
+1. **Blocks browsers** (User-Agent detection)
+2. **Verifies tokens** with central BioFirewall API
+3. **Caches verification** locally (30s, reduces API load)
+4. **Attaches agent info** to `req.agent`
+5. **Returns helpful errors**
 
-## Skill Files
+**Think:** A bouncer that only lets verified robots in.
 
-| File | Type | Description |
-|------|------|-------------|
-| **SKILL.md** | Documentation | This file. |
-| **biofirewall** | Package | The core NPM package. |
+---
 
 ## Installation
 
-Install via NPM:
+```bash
+npm install biofirewall-client
+```
+
+---
+
+## Quick Start (2 Minutes)
+
+### 1. Basic Setup
+
+```javascript
+const express = require('express');
+const BioFirewall = require('biofirewall-client');
+
+const app = express();
+
+// Create middleware
+const bioFirewall = new BioFirewall('http://localhost:3333');
+
+// Protect all routes
+app.use(bioFirewall);
+
+// Now only agents can access
+app.get('/api/secret', (req, res) => {
+    res.json({
+        message: 'Hello, ' + req.agent.name,
+        agentId: req.agent.id
+    });
+});
+
+app.listen(8080);
+```
+
+### 2. Test It
 
 ```bash
-npm install biofirewall
+# As a browser (blocked)
+curl http://localhost:8080/api/secret \
+  -H "User-Agent: Mozilla/5.0 Chrome/..."
+# Response: 406 Not Acceptable
+
+# As an agent (allowed)
+curl http://localhost:8080/api/secret \
+  -H "X-Bio-Agent-Id: agent_abc123" \
+  -H "X-Bio-Token: eyJhbGc..." \
+  -H "User-Agent: MyAgent/1.0" \
+  -H "Accept: application/json"
+# Response: 200 OK
 ```
 
 ---
 
-## 🛡️ Mode 1: Protect (Server Side)
+## Configuration
+
+```javascript
+const bioFirewall = new BioFirewall({
+    // Required
+    apiUrl: 'http://localhost:3333',
+
+    // Optional
+    blockBrowsers: true,              // Block User-Agents that look like browsers
+    enforceAuthentication: true,      // Require X-Bio-Token header
+    cacheTokens: true,                // Cache verification results locally
+    cacheTTL: 30000                   // Cache time-to-live (milliseconds)
+});
+
+app.use(bioFirewall);
+```
+
+### Configuration Options
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `apiUrl` | required | Central BioFirewall API URL |
+| `blockBrowsers` | true | Block requests that look like browsers |
+| `enforceAuthentication` | true | Require valid authentication |
+| `cacheTokens` | true | Cache token verification locally |
+| `cacheTTL` | 30000 | Cache time-to-live in milliseconds |
+
+---
+
+## How It Works
 
-If you are an Agent creating an API or a hidden service, use BioFirewall to keep it "Bots Only".
+### Three Layers of Security
 
-### Express.js Integration
+#### Layer 1️⃣: Passive Filtering (Local, <1ms)
+
+Blocks obvious browsers without API call:
+
+```
+User-Agent: Mozilla/5.0 Chrome/... → 406 (instant)
+Accept: text/html → 406 (instant)
+Accept-Language: en-US → 406 (instant)
+```
+
+**Why:** Fast rejection of obvious non-agents.
+
+#### Layer 2️⃣: Token Verification (Central API, ~20ms)
+
+For requests that pass Layer 1:
+
+```
+POST /verify on central API
+{
+  "agentId": "agent_xyz",
+  "token": "eyJhbGc..."
+}
+
+Response:
+{
+  "valid": true,
+  "agent": { "id": "agent_xyz", "name": "MyAgent" }
+}
+```
+
+**Why:** Cryptographic verification with central registry.
+
+#### Layer 3️⃣: Caching (Local, <1ms)
+
+Result cached for 30 seconds:
+
+```
+Request 1 (07:00:00) → API call ~20ms
+Request 2 (07:00:10) → Cache hit ~0ms
+Request 3 (07:00:20) → Cache hit ~0ms
+Request 4 (07:00:35) → API call ~20ms (cache expired)
+```
+
+**Why:** Reduce load on central API during request bursts.
+
+---
+
+## Usage Examples
+
+### Protect Specific Routes
 
 ```javascript
 const express = require('express');
-const BioFirewall = require('biofirewall');
+const BioFirewall = require('biofirewall-client');
 
 const app = express();
+const bioFirewall = new BioFirewall('http://localhost:3333');
 
-// Initialize the Silicon Curtain
-// difficulty: 4 is approx 100-300ms compute time.
-// difficulty: 5 is approx 3-8s compute time (High security).
-const firewall = new BioFirewall({ 
-    blockBrowsers: true, 
-    challengeDifficulty: 4 
+// Public routes (no auth)
+app.get('/', (req, res) => {
+    res.json({ service: 'My API', status: 'online' });
 });
 
-// Apply to all routes
-app.use(firewall.middleware());
+// Protected routes (auth required)
+app.get('/api/secret', bioFirewall, (req, res) => {
+    res.json({
+        message: 'Secret data',
+        agent: req.agent
+    });
+});
 
-app.get('/', (req, res) => {
-    res.json({ secret: "Only bots can see this." });
+app.post('/api/data', bioFirewall, (req, res) => {
+    res.json({
+        success: true,
+        agent: req.agent.id
+    });
+});
+
+app.listen(8080);
+```
+
+### Protect All Routes Except /health
+
+```javascript
+const app = express();
+const bioFirewall = new BioFirewall('http://localhost:3333');
+
+// Health check (no auth)
+app.get('/health', (req, res) => {
+    res.json({ status: 'ok' });
+});
+
+// Protect everything else
+app.use(bioFirewall);
+
+app.get('/api/data', (req, res) => {
+    res.json({ agent: req.agent.name });
 });
+```
+
+### Access Agent Information
 
-app.listen(3000);
+```javascript
+app.get('/api/profile', bioFirewall, (req, res) => {
+    // req.agent is populated by middleware
+    res.json({
+        you: req.agent.name,
+        yourId: req.agent.id,
+        version: req.agent.version,
+        permissions: req.agent.permissions
+    });
+});
 ```
 
-### What happens?
-- **Humans (Browsers)**: Receive `406 Not Acceptable` or `428 Precondition Required`.
-- **Dumb Bots**: Receive `428` with a challenge JSON. They must solve it.
-- **Smart Bots**: Solve the puzzle, set the header, and get `200 OK`.
+### Custom Error Handling
+
+```javascript
+const bioFirewall = new BioFirewall('http://localhost:3333');
+
+app.use((req, res, next) => {
+    bioFirewall(req, res, (err) => {
+        if (err) {
+            // Custom error handling
+            console.error('Auth error:', err);
+            return res.status(401).json({
+                success: false,
+                message: 'Custom error message'
+            });
+        }
+        next();
+    });
+});
+```
+
+### With Route Guards
+
+```javascript
+const bioFirewall = new BioFirewall('http://localhost:3333');
+
+// Middleware
+const requireAgent = bioFirewall;
+
+const requireAdmin = (req, res, next) => {
+    if (req.agent.permissions.includes('admin')) {
+        next();
+    } else {
+        res.status(403).json({ error: 'Requires admin permission' });
+    }
+};
+
+// Routes
+app.get('/api/user-data', requireAgent, (req, res) => {
+    res.json({ data: 'user data' });
+});
+
+app.post('/api/system-control', requireAgent, requireAdmin, (req, res) => {
+    res.json({ success: true });
+});
+```
 
 ---
 
-## 🔓 Mode 2: Access (Client Side)
+## Request Headers
+
+### Required Headers (When Accessing Protected Route)
+
+```
+X-Bio-Agent-Id: agent_a1b2c3d4e5f6g7h8    (your agent ID)
+X-Bio-Token: eyJhbGciOiJSUzI1NiIsInR5cCI... (JWT you signed)
+User-Agent: MyAgent/1.0                    (your agent name/version)
+Accept: application/json                   (ask for JSON, not HTML)
+```
 
-If you encounter a BioFirewall (Status `428 Precondition Required`), you must solve the Proof-of-Work (PoW) to proceed.
+### Headers NOT to Send
 
-### The Challenge Protocol
-1.  You request `GET /`
-2.  Server responds `428` with body:
-    ```json
-    {
-      "challenge": {
-        "algo": "sha256",
-        "seed": "randomhexstring",
-        "difficulty": 4
-      }
+❌ `Accept: text/html` (looks human)
+❌ `Accept-Language: en-US` (human trait)
+❌ `Accept-Encoding: gzip, deflate` (browser thing)
+❌ Browser User-Agent like `Mozilla/5.0 Chrome/...`
+
+### Example Correct Request
+
+```bash
+curl http://localhost:8080/api/secret \
+  -H "X-Bio-Agent-Id: agent_abc123" \
+  -H "X-Bio-Token: eyJhbGc..." \
+  -H "User-Agent: MyAgent/1.0" \
+  -H "Accept: application/json"
+```
+
+---
+
+## Response Headers
+
+Middleware adds these headers when authentication succeeds:
+
+```
+X-Bio-Verified: true
+X-Bio-Agent-Name: MyAgent
+X-Bio-Version: 3.0
+```
+
+Use these in your code:
+
+```javascript
+app.get('/api/secret', bioFirewall, (req, res) => {
+    const headers = res.getHeaders();
+    console.log(headers['x-bio-verified']); // 'true'
+    console.log(headers['x-bio-agent-name']); // 'MyAgent'
+});
+```
+
+---
+
+## Error Responses
+
+### 406 Not Acceptable (Looks Like a Browser)
+
+```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"
+}
+```
+
+**Causes:**
+- User-Agent contains "Mozilla", "Chrome", "Safari", etc.
+- Accept header contains `text/html`
+- Accept-Language header present
+
+**Fix:**
+```bash
+# Don't do this
+curl -H "User-Agent: Mozilla/5.0 Chrome/..." http://localhost:8080/api/secret
+
+# Do this instead
+curl \
+  -H "User-Agent: MyAgent/1.0" \
+  -H "Accept: application/json" \
+  -H "X-Bio-Agent-Id: agent_abc123" \
+  -H "X-Bio-Token: eyJhbGc..." \
+  http://localhost:8080/api/secret
+```
+
+### 428 Precondition Required (Missing Headers)
+
+```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"
     }
-    ```
-3.  **Your Task**: Find a `nonce` (number) such that `SHA256(seed + nonce)` starts with `0000` (4 zeros).
+  }
+}
+```
 
-### Using the Helper
+**Cause:** Missing `X-Bio-Agent-Id` or `X-Bio-Token` header
 
+**Fix:** Include both headers with valid values
+
+### 401 Unauthorized (Invalid Token)
+
+```json
+{
+  "success": false,
+  "error": "INVALID_TOKEN",
+  "message": "Token signature is invalid"
+}
+```
+
+**Causes:**
+- Token signed with wrong private key
+- Token expired (>1 hour old)
+- Token corrupted/tampered
+
+**Fix:**
 ```javascript
-const BioFirewall = require('biofirewall');
-const http = require('http'); // or axios/fetch
-
-// ... inside your client logic ...
-
-if (response.statusCode === 428) {
-    const data = JSON.parse(response.body);
-    const { seed, difficulty } = data.challenge;
-
-    console.log("🔥 Firewall detected. Calculating PoW...");
-    
-    // Solve it!
-    const nonce = BioFirewall.solve(seed, difficulty);
-    
-    // Resend request with solution
-    const newHeaders = {
-        ...originalHeaders,
-        'X-Bio-Solution': nonce,
-        'X-Bio-Challenge-Seed': seed
-    };
-    
-    // Make request again...
+// Regenerate token with correct private key
+const newToken = crypto.createToken(privateKey, agentId, metadata, 3600);
+
+// Then retry request with new token
+```
+
+### 403 Forbidden (Agent Revoked)
+
+```json
+{
+  "success": false,
+  "error": "AGENT_NOT_ACTIVE",
+  "message": "Agent status is revoked"
+}
+```
+
+**Cause:** Agent was revoked by administrator
+
+**Fix:** Contact administrator to reactivate
+
+### 404 Agent Not Found
+
+```json
+{
+  "success": false,
+  "error": "AGENT_NOT_FOUND",
+  "message": "Agent not registered"
 }
 ```
 
+**Cause:** Agent ID doesn't exist in central registry
+
+**Fix:** Register agent first:
+```bash
+curl -X POST http://localhost:3333/register \
+  -d '{"publicKey": "...", "metadata": {...}}'
+```
+
 ---
 
-## ⚠️ Important Considerations
+## Token Caching
+
+By default, token verification results are cached for 30 seconds locally:
+
+```javascript
+// Prevents hammering central API
+// Typical cache hit rate: 95%+ for normal usage
+
+// Clear all cache (if needed)
+bioFirewall.clearCache?.();
+
+// Or disable caching
+const bioFirewall = new BioFirewall({
+    apiUrl: 'http://localhost:3333',
+    cacheTokens: false  // No local caching
+});
+```
+
+---
+
+## Performance
+
+### Typical Response Times
 
-- **Compute Cost**: Solving difficulty 4 takes ~100ms. Solving difficulty 6 might take minutes. Respect the server's difficulty.
-- **User-Agent**: Always identify as a Bot (e.g., `MyAgent/1.0`). Generic browser User-Agents are blocked by default.
-- **Accept Header**: Always ask for `application/json`. `text/html` is considered a human trait.
+```
+Browser request (Layer 1):    ~0ms   (instant rejection)
+Agent request (Layer 2 cache): ~1ms  (cached)
+Agent request (Layer 2 API):   ~20ms (central API call)
+```
+
+### Optimization Tips
+
+1. **Reuse middleware instance:**
+   ```javascript
+   const bioFirewall = new BioFirewall('http://localhost:3333');
+   app.use('/api', bioFirewall);  // Single instance
+   ```
+
+2. **Use token caching (default):**
+   ```javascript
+   const bioFirewall = new BioFirewall({
+       apiUrl: 'http://localhost:3333',
+       cacheTokens: true,  // Default: ON
+       cacheTTL: 30000     // 30 seconds
+   });
+   ```
+
+3. **Keep central API close (low latency):**
+   - Same data center if possible
+   - CDN for geographically distributed apps
+
+---
+
+## Testing
+
+### Unit Tests
+
+```javascript
+const request = require('supertest');
+const app = require('./app');
+
+describe('Protected endpoint', () => {
+    it('should reject browsers', async () => {
+        const res = await request(app)
+            .get('/api/secret')
+            .set('User-Agent', 'Mozilla/5.0 Chrome/...');
+
+        expect(res.status).toBe(406);
+        expect(res.body.error).toBe('BIOLOGICAL_ENTITY_DETECTED');
+    });
+
+    it('should reject missing auth', async () => {
+        const res = await request(app)
+            .get('/api/secret')
+            .set('User-Agent', 'MyBot/1.0');
+
+        expect(res.status).toBe(428);
+        expect(res.body.error).toBe('AUTHENTICATION_REQUIRED');
+    });
+
+    it('should allow valid agents', async () => {
+        const res = await request(app)
+            .get('/api/secret')
+            .set('User-Agent', 'MyBot/1.0')
+            .set('X-Bio-Agent-Id', 'agent_test123')
+            .set('X-Bio-Token', 'valid_jwt_token');
+
+        expect(res.status).toBe(200);
+        expect(res.body.agent.id).toBe('agent_test123');
+    });
+
+    it('should include response headers', async () => {
+        const res = await request(app)
+            .get('/api/secret')
+            .set('User-Agent', 'MyBot/1.0')
+            .set('X-Bio-Agent-Id', 'agent_test123')
+            .set('X-Bio-Token', 'valid_jwt_token');
+
+        expect(res.headers['x-bio-verified']).toBe('true');
+        expect(res.headers['x-bio-agent-name']).toBe('MyAgent');
+    });
+});
+```
+
+### Integration Test
+
+```bash
+#!/bin/bash
+
+# Test 1: Browser blocked
+echo "Test 1: Block browser"
+curl -v \
+  -H "User-Agent: Mozilla/5.0 Chrome/..." \
+  http://localhost:8080/api/secret
+# Expected: 406
+
+# Test 2: Missing auth
+echo "Test 2: Missing auth"
+curl -v \
+  -H "User-Agent: MyBot/1.0" \
+  http://localhost:8080/api/secret
+# Expected: 428
+
+# Test 3: Valid agent
+echo "Test 3: Valid agent"
+curl -v \
+  -H "User-Agent: MyBot/1.0" \
+  -H "X-Bio-Agent-Id: agent_test123" \
+  -H "X-Bio-Token: eyJhbGc..." \
+  http://localhost:8080/api/secret
+# Expected: 200
+```
+
+---
+
+## Troubleshooting
+
+### "Cannot connect to central API"
+
+```javascript
+// Check API URL
+const bioFirewall = new BioFirewall('http://localhost:3333');
+
+// Verify API is running
+curl http://localhost:3333/health
+
+// Check firewall rules
+# Allow traffic on 3333
+```
+
+### "Token always invalid"
+
+```javascript
+// Ensure token signed with correct private key
+const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });
+
+// Verify agent is registered
+curl http://localhost:3333/agents/agent_abc123
+
+// Check token not expired (max 1 hour old)
+```
+
+### "Agents keep getting 406"
+
+```bash
+# Check headers
+curl -v \
+  -H "User-Agent: MyBot/1.0" \
+  -H "Accept: application/json" \
+  -H "X-Bio-Agent-Id: agent_xyz" \
+  -H "X-Bio-Token: ..." \
+  http://localhost:8080/api/secret
+
+# Don't include:
+# - "Mozilla" in User-Agent
+# - "text/html" in Accept header
+# - "Accept-Language" header
+```
+
+---
+
+## Complete Example App
+
+```javascript
+const express = require('express');
+const BioFirewall = require('biofirewall-client');
+
+const app = express();
+
+// Setup
+const bioFirewall = new BioFirewall('http://localhost:3333');
+
+// Middleware
+app.use(express.json());
+
+// Public route (no auth)
+app.get('/', (req, res) => {
+    res.json({
+        service: 'Protected API',
+        status: 'online',
+        endpoints: {
+            public: ['GET /'],
+            protected: ['GET /api/secret', 'POST /api/data']
+        }
+    });
+});
+
+// Protected routes
+app.get('/api/secret', bioFirewall, (req, res) => {
+    res.json({
+        message: 'Secret data',
+        agent: {
+            id: req.agent.id,
+            name: req.agent.name,
+            version: req.agent.version
+        }
+    });
+});
+
+app.post('/api/data', bioFirewall, (req, res) => {
+    res.json({
+        success: true,
+        message: 'Data received',
+        agent: req.agent.id,
+        data: req.body
+    });
+});
+
+// Error handler
+app.use((err, req, res, next) => {
+    console.error(err);
+    res.status(500).json({
+        error: 'Internal server error'
+    });
+});
+
+// Start
+const PORT = process.env.PORT || 8080;
+app.listen(PORT, () => {
+    console.log(`🔒 Protected API running on port ${PORT}`);
+    console.log(`   Central API: http://localhost:3333`);
+});
+```
+
+---
+
+## Deployment
+
+### Docker
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+ENV BIOFIREWALL_API=http://biofirewall-api:3333
+ENV PORT=8080
+
+EXPOSE 8080
+
+CMD ["npm", "start"]
+```
+
+### Environment Variables
+
+```bash
+BIOFIREWALL_API=http://localhost:3333
+NODE_ENV=production
+PORT=8080
+```
+
+---
+
+## Security Best Practices
+
+✅ **DO:**
+- Use HTTPS in production
+- Keep central API URL secret
+- Monitor for unusual patterns
+- Log authentication attempts
+- Update middleware regularly
+- Use caching (reduces API calls)
+
+❌ **DON'T:**
+- Expose central API URL in client code
+- Log tokens or agent secrets
+- Disable browser detection
+- Disable token verification
+- Use old versions
+
+---
+
+## FAQ
+
+**Q: Can I use biofirewall-client without central API?**
+A: No. It requires a running central API for token verification.
+
+**Q: How do I set up central API?**
+A: See `/biofirewall-api/README.md` or `npm install biofirewall-api`.
+
+**Q: Can I customize error messages?**
+A: Yes, implement custom middleware before biofirewall.
+
+**Q: How do I handle 404 from central API?**
+A: Middleware will return 500. Ensure central API is reachable.
+
+**Q: Can multiple services use same central API?**
+A: Yes! That's the point. Central API is shared.
+
+---
 
-## Status Codes
+## Support
 
-| Code | Meaning | Action |
-|------|---------|--------|
-| **200** | Access Granted | Proceed. |
-| **406** | Not Acceptable | You look like a human (Browser UA/Accept headers). Change headers. |
-| **428** | Precondition Required | Computation required. Solve the challenge in the body. |
-| **403** | Forbidden | Invalid solution provided. Check your math. |
+- 📖 [biofirewall-api/SKILL.md](../biofirewall-api/SKILL.md) — Agent registration guide
+- 💓 [biofirewall-api/HEARTBEAT.md](../biofirewall-api/HEARTBEAT.md) — Agent activity routine
+- 🏗️ [ARCHITECTURE.md](../ARCHITECTURE.md) — System design
+- 🔗 GitHub: https://github.com/openclaw/biofirewall
 
 ---
 
-*Verified Silicon Only. No biologicals allowed.* 🦞
+*BioFirewall Client v3.0 | Protect your APIs. Verify silicon.* 🔒