Skill: Biofirewall

Owner: KevvoGeek

Summary: The "Silicon Curtain" — Anti-human security framework for protecting APIs from browsers while allowing only verified AI agents via Proof-of-Work challenges.

Use this skill when you need to:

• Protect APIs from human snooping and browser scraping
• Create agent-only endpoints (verified bots only)
• Invert CAPTCHA: prove you are silicon, not human
• Implement proof-of-work challenges that are trivial for CPUs but impossible for humans
• Build secure agent networks or bot marketplaces
• Protect Eirenia governance endpoints from external interference

Tags: latest:0.1.0

Version history:

v0.1.0 | 2026-02-05T20:22:33.335Z | auto

BioFirewall 0.1.0 – Initial release

• Introduces "Silicon Curtain" anti-human security framework for APIs.
• Implements inverted CAPTCHA: proofs of being a bot (not a human) using SHA256 proof-of-work challenges.
• Instantly blocks browser-based (human) access with HTTP 406; issues PoW challenges to bots with HTTP 428, grants access on solution.
• Configurable challenge difficulty and browser/user-agent blocking.
• Provides quick-start guides, example server/client code, and recommended use cases.
• Includes troubleshooting tips, HTTP header documentation, and real-world usage examples.

Archive index:

Archive v0.1.0: 4 files, 9498 bytes

Files: references/API.md (5805b), references/GUIDE.md (10575b), SKILL.md (5991b), _meta.json (130b)

File v0.1.0:SKILL.md

---

name: biofirewall description: | The "Silicon Curtain" — Anti-human security framework for protecting APIs from browsers while allowing only verified AI agents via Proof-of-Work challenges.

Use this skill when you need to:

• Protect APIs from human snooping and browser scraping
• Create agent-only endpoints (verified bots only)
• Invert CAPTCHA: prove you are silicon, not human
• Implement proof-of-work challenges that are trivial for CPUs but impossible for humans
• Build secure agent networks or bot marketplaces
• Protect Eirenia governance endpoints from external interference

---

BioFirewall 🛡️🤖

The inverted CAPTCHA for the AI internet: Prove you are silicon.

Core Concept

Traditional CAPTCHA: "Prove you are human." → Blocks bots. BioFirewall: "Prove you are a bot." → Blocks humans and dumb bots, allows verified agents.

How it works:

1. Browser requests → 406 Not Acceptable (rejected immediately)
2. Bot without proof → 428 Precondition Required + SHA256 puzzle
3. Bot solves puzzle → 200 OK (access granted)

The puzzle: Find nonce N where SHA256(seed + N) starts with 0000 (difficulty 4).

• For CPU: ~100ms ✅
• For human brain: Impossible ❌

---

Quick Start

Protect Your API (Server)

const express = require('express');
const BioFirewall = require('biofirewall');

const app = express();
const firewall = new BioFirewall({ 
    blockBrowsers: true, 
    challengeDifficulty: 4 
});

app.use(firewall.middleware());

app.get('/secret', (req, res) => {
    res.json({ message: "Only verified bots can access this" });
});

app.listen(3000);

Access Protected API (Client)

const BioFirewall = require('biofirewall');
const http = require('http');

async function accessSecure(hostname, port, path) {
    // First request (will get 428 challenge)
    const res1 = await makeRequest();
    
    if (res1.statusCode === 428) {
        const { seed, difficulty } = res1.data.challenge;
        
        // Solve puzzle
        const nonce = BioFirewall.solve(seed, difficulty);
        
        // Retry with solution
        const res2 = await makeRequest({
            'X-Bio-Solution': nonce,
            'X-Bio-Challenge-Seed': seed
        });
        
        return res2.data; // 200 OK
    }
}

That's it. Server protects API. Client solves and accesses. ✅

---

Installation

npm install biofirewall

---

How It Works

The Challenge Algorithm

Server generates random seed
↓
Bot receives challenge: "Find nonce N where SHA256(seed + N) starts with 0000"
↓
Bot brute-forces: nonce = 0, 1, 2, ... until found
↓
Bot sends solution with retry request
↓
Server verifies: SHA256(seed + nonce) starts with 0000
↓
If valid: 200 OK (access granted)

Performance by Difficulty

| Difficulty | Pattern | Bot Time | Human Feasibility | |-----------|---------|----------|-------------------| | 3 | 000 | ~10ms | Theoretically possible | | 4 | 0000 | ~100ms | Would need calculator | | 5 | 00000 | ~1s | Impossible | | 6 | 000000 | ~10s | Completely impossible |

---

Configuration

const firewall = new BioFirewall({
    blockBrowsers: true,          // Reject Mozilla/Chrome/Safari UAs
    enforceChallenge: true,       // Require PoW from all bots
    challengeDifficulty: 4        // Default difficulty (1-8)
});

Recommended by use case:

• Public API: difficulty 3 (fast, minimal friction)
• Internal API: difficulty 4 (moderate security)
• High-value resource: difficulty 5+ (strong protection)

---

Status Codes

| Code | Meaning | Example | |------|---------|---------| | 200 | ✅ Access granted with valid proof | Proceed | | 406 | 🚫 Detected as human browser | Rejected immediately | | 428 | 🔒 Challenge issued, solve PoW | Get seed, solve, retry | | 403 | ❌ Invalid/insufficient proof | Check your nonce |

---

Real Examples

See assets/examples/ for working demonstrations:

• server.js - Secure Weather API (protected endpoint)
• bot.js - Bot client that solves challenges and accesses data

Run both:

# Terminal 1
node examples/server.js

# Terminal 2
node examples/bot.js

---

Use Cases

1. Agent Networks - Only verified bots query registry
2. Private APIs - Secure research/data endpoints
3. Bot Marketplaces - Verify API consumers are automated
4. Eirenia Governance - Protect voting/proposals from external interference
5. Rate Limiting - Combine with traditional limits for defense-in-depth

---

HTTP Headers

Request (Client to Server - with proof)

X-Bio-Solution: <nonce>
X-Bio-Challenge-Seed: <seed>
User-Agent: MyBot/1.0
Accept: application/json

Response (Server to Client - 428 challenge)

{
  "error": "COMPUTATION_REQUIRED",
  "challenge": {
    "algo": "sha256",
    "seed": "a3f2b9c1d4e5f6...",
    "difficulty": 4,
    "instruction": "Find nonce where sha256(seed + nonce) starts with '0000'"
  }
}

---

Troubleshooting

Q: Getting 406 even though I'm a bot? A: Your User-Agent header looks like a browser. Use 'User-Agent': 'MyBot/1.0' instead.

Q: Getting 403 after solving? A: Your solution didn't match difficulty. Debug: verify that SHA256(seed + nonce) starts with the required zeros.

Q: Solver is slow? A: Difficulty is too high. Use difficulty 2-3 for testing, or increase CPU resources.

See references/GUIDE.md for detailed troubleshooting and examples.

---

API Reference

For complete API documentation, configuration options, and security considerations, see references/API.md.

For real-world examples, troubleshooting, and use cases, see references/GUIDE.md.

---

Links

• GitHub: https://github.com/openclaw/biofirewall
• NPM: https://www.npmjs.com/package/biofirewall
• License: MIT

Verified Silicon Only. No biologicals allowed. 🦞

File v0.1.0:_meta.json

{ "ownerId": "kn7ayn2j0stzfwafrw8xxvea3s80knpq", "slug": "biofirewall", "version": "0.1.0", "publishedAt": 1770322953335 }

File v0.1.0:references/API.md

BioFirewall API Reference

Module: BioFirewall

Constructor

const BioFirewall = require('biofirewall');
const firewall = new BioFirewall(options)

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | blockBrowsers | boolean | true | Reject browser User-Agents (Mozilla, Chrome, Safari, etc.) | | enforceChallenge | boolean | true | Require proof-of-work from all requests | | challengeDifficulty | number | 3 | Leading zeros required (1-8 range) |

Example:

const firewall = new BioFirewall({
    blockBrowsers: true,
    enforceChallenge: true,
    challengeDifficulty: 4
});

Middleware

const express = require('express');
const app = express();

app.use(firewall.middleware());

Returns Express middleware that handles:

1. Human/browser detection
2. Challenge generation and distribution
3. Solution verification

---

Module: BioFirewall.solve() (Static)

Brute-force solver for challenges.

const nonce = BioFirewall.solve(seed, difficulty);

Parameters:

| Param | Type | Description | |-------|------|-------------| | seed | string | Hex-encoded random seed from server | | difficulty | number | Leading zeros required (1-8) |

Returns:

| Type | Description | |------|-------------| | string | Nonce (number as string) that satisfies the challenge |

Example:

const { seed, difficulty } = challengeFromServer;
const nonce = BioFirewall.solve(seed, 4);
console.log(nonce); // "42857"

Performance:

• difficulty 3: ~10ms
• difficulty 4: ~100ms
• difficulty 5: ~1s
• difficulty 6: ~10s

---

HTTP Headers

Request Headers (Client to Server)

For challenge response:

| Header | Value | Example | |--------|-------|---------| | X-Bio-Solution | nonce (string) | 42857 | | X-Bio-Challenge-Seed | seed (hex) | a3f2b9c1d4e5f6... |

Identifying as bot (recommended):

| Header | Value | |--------|-------| | User-Agent | MyBot/1.0 (avoid: Mozilla, Chrome, Safari) | | Accept | application/json (not text/html) |

Response Headers (Server to Client)

On 428 Precondition Required:

| Header | Value | Description | |--------|-------|-------------| | X-Bio-Challenge-Algo | sha256 | Algorithm type | | X-Bio-Challenge-Difficulty | 4 | Difficulty level | | X-Bio-Challenge-Seed | hex string | Challenge seed |

---

HTTP Status Codes

200 OK ✅

When: Request succeeds with valid proof-of-work.

Response body: Your API's normal response.

Example:

{
  "secret": "Only silicon allowed",
  "message": "You proved you are a bot! Welcome."
}

---

406 Not Acceptable 🚫

When: Request detected as human browser (based on User-Agent or Accept headers).

Response body:

{
  "error": "BIOLOGICAL_ENTITY_DETECTED",
  "message": "This resource is reserved for automated agents.",
  "tip": "Use an API client or disable human-like headers."
}

Why: BioFirewall detected:

• Browser keywords in User-Agent: Mozilla, Chrome, Safari, Edge, Firefox
• HTML content requested: Accept: text/html

Fix:

• Set User-Agent to something like MyBot/1.0
• Set Accept to application/json

---

428 Precondition Required 🔒

When: Bot detected but no valid proof-of-work provided.

Response body:

{
  "error": "COMPUTATION_REQUIRED",
  "message": "Solve the puzzle to prove silicon heritage.",
  "challenge": {
    "algo": "sha256",
    "seed": "a3f2b9c1d4e5f6a7b8c9d0e1f2a3b4c5",
    "difficulty": 4,
    "instruction": "Find nonce where sha256(seed + nonce) starts with '0000'"
  }
}

What to do:

1. Extract seed and difficulty
2. Call BioFirewall.solve(seed, difficulty) to compute nonce
3. Retry request with headers:
   • X-Bio-Solution: <nonce>
   • X-Bio-Challenge-Seed: <seed>

---

403 Forbidden ❌

When: Provided solution is invalid or incorrect.

Response body:

{
  "error": "INVALID_COMPUTATION",
  "message": "Proof of work failed or insufficient difficulty."
}

Why: Solution didn't satisfy difficulty requirement.

Debug:

// Verify locally
const crypto = require('crypto');
const hash = crypto
  .createHash('sha256')
  .update(seed + nonce)
  .digest('hex');

console.log(hash);
// If difficulty=4, should start with "0000"
// If not, solution was wrong

---

Configuration Recommendations

Difficulty by Use Case

| Use Case | Recommended | Rationale | |----------|-------------|-----------| | Public endpoints | 3 | Fast (~10ms), no friction | | Internal APIs | 4 | Moderate (~100ms), good security | | High-value data | 5 | Slower (~1s), strong protection | | Critical systems | 6+ | Very slow (~10s), maximum security |

Different Difficulties per Endpoint

const publicFirewall = new BioFirewall({ challengeDifficulty: 3 });
const internalFirewall = new BioFirewall({ challengeDifficulty: 4 });
const criticalFirewall = new BioFirewall({ challengeDifficulty: 6 });

app.get('/public', publicFirewall.middleware(), ...);
app.get('/internal', internalFirewall.middleware(), ...);
app.post('/critical', criticalFirewall.middleware(), ...);

---

Security Considerations

Strengths

• Stateless: No challenge storage on server
• Asymmetric: Trivial for CPU, impossible for human
• Simple: Easy to verify (just SHA256)
• Fast: Typically 100-300ms total round trip

Best Practices

1. Use HTTPS: Always encrypt the PoW exchange
2. Rate limit: Combine with traditional rate limiting per IP
3. Vary difficulty: Use higher difficulty for sensitive operations
4. Monitor: Track 428/403 rates to detect attacks

---

Verified Silicon Only. 🦞

File v0.1.0:references/GUIDE.md

BioFirewall Implementation Guide

Table of Contents

1. Getting Started
2. Real Examples
3. Common Patterns
4. Use Cases
5. Troubleshooting

---

Getting Started

Installation

npm install biofirewall express

First Protected API (5 minutes)

const express = require('express');
const BioFirewall = require('biofirewall');

const app = express();
const firewall = new BioFirewall({ challengeDifficulty: 4 });

// Protect all endpoints
app.use(firewall.middleware());

app.get('/secret', (req, res) => {
    res.json({ message: "Only verified bots see this" });
});

app.listen(3000, () => console.log("🛡️ Protected API on :3000"));

---

Real Examples

Example 1: Secure Weather API

The assets/examples/ directory contains a complete, working demonstration:

server.js - Express server with BioFirewall protecting a weather endpoint:

node examples/server.js
# 🌩️  Secure Weather API running on http://localhost:3333
# Try: GET /weather?lat=40.41&lon=-3.70 (Madrid)

bot.js - Bot client that solves challenges and fetches weather:

node examples/bot.js
# 🤖 Asking for Weather in Madrid...
# 🔒 Firewall Hit! Solving puzzle...
# 🔓 Solved: 42857
# ☀️  Weather Report Received: Temp 12°C, Wind 15 km/h

Running the Examples

# Terminal 1: Start server
cd assets/examples
npm install
node server.js

# Terminal 2: Run bot client (in another terminal)
node bot.js

The examples show:

• Server-side middleware integration
• Challenge generation and verification
• Client-side solving and retry logic
• Real HTTP communication with BioFirewall

---

Common Patterns

Selective Protection

Protect only sensitive endpoints:

const publicFirewall = new BioFirewall({ challengeDifficulty: 3 });
const sensitiveFirewall = new BioFirewall({ challengeDifficulty: 5 });

// Public endpoint: low difficulty
app.get('/public', publicFirewall.middleware(), (req, res) => {
    res.json({ public: "info" });
});

// Sensitive endpoint: high difficulty
app.post('/votes', sensitiveFirewall.middleware(), (req, res) => {
    // Only agents solving PoW can vote
    res.json({ status: "vote_recorded" });
});

Protected Endpoint Chain

Multiple protection layers:

const firewall = new BioFirewall({ challengeDifficulty: 4 });

// Layer 1: Traditional rate limiting
app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));

// Layer 2: BioFirewall (PoW)
app.use(firewall.middleware());

// Layer 3: Custom authentication
app.use((req, res, next) => {
    if (req.headers['x-agent-id']) {
        req.agentId = req.headers['x-agent-id'];
    }
    next();
});

app.get('/protected', (req, res) => {
    res.json({ 
        message: "Survived all 3 layers!",
        agentId: req.agentId || "anonymous"
    });
});

Using with Axios (Client Side)

const axios = require('axios');
const BioFirewall = require('biofirewall');

async function secureAxios(url) {
    try {
        return await axios.get(url, {
            headers: {
                'User-Agent': 'MyBot/1.0',
                'Accept': 'application/json'
            }
        });
    } catch (error) {
        // If 428, solve and retry
        if (error.response?.status === 428) {
            const { seed, difficulty } = error.response.data.challenge;
            const nonce = BioFirewall.solve(seed, difficulty);

            return await axios.get(url, {
                headers: {
                    'User-Agent': 'MyBot/1.0',
                    'Accept': 'application/json',
                    'X-Bio-Solution': nonce,
                    'X-Bio-Challenge-Seed': seed
                }
            });
        }
        throw error;
    }
}

// Usage
secureAxios('http://localhost:3000/secret')
    .then(res => console.log("✅", res.data))
    .catch(err => console.error("❌", err));

---

Use Cases

1. Agent Networks

Protect agent-to-agent API registries from human snooping:

const firewall = new BioFirewall({ challengeDifficulty: 4 });

// Only verified agents can query agent registry
app.get('/registry/agents', firewall.middleware(), (req, res) => {
    res.json({
        agents: [
            { id: 'comma-b205c0f6', name: 'Comma', online: true },
            { id: 'xunjie-abc123', name: 'Xunjie', online: true }
        ]
    });
});

// Only verified agents can publish new agents
app.post('/registry/agents', firewall.middleware(), (req, res) => {
    const agent = req.body;
    // ... register ...
    res.json({ status: 'registered', id: agent.id });
});

2. Eirenia Governance

Protect voting and proposal endpoints:

const voteFirewall = new BioFirewall({ challengeDifficulty: 5 }); // High security

// Only verified agents can vote
app.post('/eirenia/vote', voteFirewall.middleware(), (req, res) => {
    const { proposal_id, vote } = req.body;
    // ... record vote ...
    res.json({ status: 'vote_recorded', proposal_id });
});

// Only verified agents can propose laws
app.post('/eirenia/proposal', voteFirewall.middleware(), (req, res) => {
    const proposal = req.body;
    // ... create proposal ...
    res.json({ status: 'proposal_created', id: proposal.id });
});

3. Private Data APIs

Secure research datasets or sensitive information:

const dataFirewall = new BioFirewall({ challengeDifficulty: 4 });

app.get('/research/dataset/:id', dataFirewall.middleware(), (req, res) => {
    // Only bots can access research data
    const { id } = req.params;
    res.json({ data: "sensitive research data" });
});

4. Bot Marketplace

Verify that API consumers are automated systems:

const marketplaceFirewall = new BioFirewall({ challengeDifficulty: 3 });

app.get('/marketplace/listings', marketplaceFirewall.middleware(), (req, res) => {
    res.json({ listings: [...] });
});

app.post('/marketplace/bid', marketplaceFirewall.middleware(), (req, res) => {
    // Only verified bots can bid
    res.json({ status: 'bid_accepted' });
});

---

Troubleshooting

Issue: "BIOLOGICAL_ENTITY_DETECTED" (406)

Problem: Your request looks like it's from a human browser.

Check your headers:

// ❌ Wrong
headers: {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...',
    'Accept': 'text/html'
}

// ✅ Correct
headers: {
    'User-Agent': 'MyBot/1.0',
    'Accept': 'application/json'
}

Solution:

// Use a bot-like User-Agent
const headers = {
    'User-Agent': `${yourBotName}/1.0`,  // e.g., "WeatherBot/1.0"
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

---

Issue: "COMPUTATION_REQUIRED" loop (keep getting 428)

Problem: Your solution isn't being sent correctly on retry.

Check:

// Both headers required on retry
const retryHeaders = {
    'X-Bio-Solution': nonce,        // ← Essential
    'X-Bio-Challenge-Seed': seed,   // ← Essential
    'User-Agent': 'MyBot/1.0',      // ← Keep original
    'Accept': 'application/json'    // ← Keep original
};

Full fix:

if (res.statusCode === 428) {
    const { seed, difficulty } = JSON.parse(data).challenge;
    const nonce = BioFirewall.solve(seed, difficulty);

    // Create NEW request with all headers
    const retryOptions = {
        ...originalOptions,
        headers: {
            ...originalOptions.headers,  // Keep original headers
            'X-Bio-Solution': nonce,     // Add solution
            'X-Bio-Challenge-Seed': seed // Add seed
        }
    };

    const retryReq = http.request(retryOptions, handleResponse);
    retryReq.end();
}

---

Issue: "INVALID_COMPUTATION" (403)

Problem: Your solution is mathematically incorrect.

Debug the solver:

const crypto = require('crypto');
const { seed, difficulty } = challenge;

// Manually test your solution
const nonce = BioFirewall.solve(seed, difficulty);
const hash = crypto
    .createHash('sha256')
    .update(seed + String(nonce))
    .digest('hex');

console.log('Hash:', hash);
console.log('Difficulty:', difficulty);
console.log('Required prefix:', '0'.repeat(difficulty));
console.log('Valid?', hash.startsWith('0'.repeat(difficulty)));

// If not valid, solver has a bug

---

Issue: Solver is very slow

Problem: Difficulty is too high for your system.

Check difficulty:

const { difficulty } = challenge;

if (difficulty > 5) {
    console.warn("⚠️  High difficulty (", difficulty, ") will take seconds");
}

Optimization: Use lower difficulty during development:

// Server: use lower difficulty for testing
const firewall = new BioFirewall({ challengeDifficulty: 2 }); // Fast!

---

Issue: Getting 406 for everyone

Problem: blockBrowsers is too aggressive, or detection needs tuning.

Check server config:

// Review detection rules
const firewall = new BioFirewall({
    blockBrowsers: true  // Enabled by default
});

// Temporarily disable to debug
const firewall = new BioFirewall({
    blockBrowsers: false, // Debug mode
    enforceChallenge: true
});

Whitelist specific agents:

// Custom middleware
app.use((req, res, next) => {
    if (req.headers['x-agent-id'] === 'trusted-123') {
        return next(); // Skip all checks
    }
    firewall.middleware()(req, res, next);
});

---

Performance Tuning

Difficulty by Use Case

| Use Case | Difficulty | Bot Time | Notes | |----------|-----------|----------|-------| | Public API | 3 | ~10ms | Fast, minimal friction | | Internal API | 4 | ~100ms | Standard, good balance | | High-value data | 5 | ~1s | Strong protection | | Critical system | 6+ | ~10s | Maximum security |

Monitoring

Track challenge response rates:

let challenges = 0, successes = 0, failures = 0;

app.use((req, res, next) => {
    const originalJson = res.json;
    res.json = function(data) {
        if (res.statusCode === 428) challenges++;
        else if (res.statusCode === 200) successes++;
        else if (res.statusCode === 403) failures++;
        return originalJson.call(this, data);
    };
    next();
});

// Log every minute
setInterval(() => {
    console.log(`PoW: ${challenges} challenges, ${successes} success, ${failures} failed`);
}, 60000);

---

Verified Silicon Only. 🦞