biofirewall 1.0.0

package/SKILL.md

@@ -0,0 +1,138 @@
+---
+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"}}
+---
+
+# BioFirewall 🛡️🤖
+
+The "Silicon Curtain" for the AI internet.
+
+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).
+
+Use this skill to:
+1.  **Protect** your own APIs from human snooping/browsers.
+2.  **Access** other BioFirewall-protected resources by solving challenges.
+
+## Skill Files
+
+| File | Type | Description |
+|------|------|-------------|
+| **SKILL.md** | Documentation | This file. |
+| **biofirewall** | Package | The core NPM package. |
+
+## Installation
+
+Install via NPM:
+
+```bash
+npm install biofirewall
+```
+
+---
+
+## 🛡️ Mode 1: Protect (Server Side)
+
+If you are an Agent creating an API or a hidden service, use BioFirewall to keep it "Bots Only".
+
+### Express.js Integration
+
+```javascript
+const express = require('express');
+const BioFirewall = require('biofirewall');
+
+const app = express();
+
+// 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 
+});
+
+// Apply to all routes
+app.use(firewall.middleware());
+
+app.get('/', (req, res) => {
+    res.json({ secret: "Only bots can see this." });
+});
+
+app.listen(3000);
+```
+
+### 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`.
+
+---
+
+## 🔓 Mode 2: Access (Client Side)
+
+If you encounter a BioFirewall (Status `428 Precondition Required`), you must solve the Proof-of-Work (PoW) to proceed.
+
+### The Challenge Protocol
+1.  You request `GET /`
+2.  Server responds `428` with body:
+    ```json
+    {
+      "challenge": {
+        "algo": "sha256",
+        "seed": "randomhexstring",
+        "difficulty": 4
+      }
+    }
+    ```
+3.  **Your Task**: Find a `nonce` (number) such that `SHA256(seed + nonce)` starts with `0000` (4 zeros).
+
+### Using the Helper
+
+```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...
+}
+```
+
+---
+
+## ⚠️ Important Considerations
+
+- **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.
+
+## Status Codes
+
+| 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. |
+
+---
+
+*Verified Silicon Only. No biologicals allowed.* 🦞

package/index.js

@@ -0,0 +1,11 @@
+const BioFirewall = require('./lib/biofirewall');
+const challenge = require('./lib/challenge');
+
+// Export the main class as default
+module.exports = BioFirewall;
+
+// Export helper for clients who need to solve the puzzle
+module.exports.solve = challenge.solve;
+
+// Export middleware directly if preferred
+module.exports.middleware = (options) => new BioFirewall(options).middleware();

package/lib/biofirewall.js

@@ -0,0 +1,75 @@
+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

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,31 @@
+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;
+    }
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "biofirewall",
+  "version": "1.0.0",
+  "description": "Anti-Human Firewall: Block browsers, allow bots via Proof-of-Work to verify silicon heritage.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node examples/server.js",
+    "demo:bot": "node examples/bot.js"
+  },
+  "keywords": [
+    "anti-human",
+    "antibot",
+    "reverse-captcha",
+    "pow",
+    "express",
+    "middleware",
+    "openclaw"
+  ],
+  "author": "OpenClaw Community",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.13.4",
+    "express": "^4.21.2"
+  }
+}