npm package: @h33/botshield
Description: H33-BotShield — Proof-of-work bot prevention without CAPTCHA. No tracking. No images. Just math.
Author: H33.ai, Inc.
Latest version: 1.0.0

# H33-BotShield

**Proof-of-work bot prevention. No CAPTCHAs. No tracking. Just math.**

Replace reCAPTCHA, hCaptcha, and Turnstile with a single script tag. Your visitor's browser solves a cryptographic challenge invisibly — no images, no checkboxes, no Google.

Free for 10,000 challenges per month.

## Quick Start

### Script Tag (zero code)

```html
<script src="https://api.h33.ai/v1/botshield/script.js"></script>
```

Done. The script auto-solves on page load and stores the session token.

### npm

```bash
npm install @h33/botshield
```

```javascript
import { protect, getToken, createProtectedFetch } from '@h33/botshield';

// Auto-challenge + solve + store token
await protect();

// Get the token for your own requests
const token = getToken();

// Or wrap fetch to auto-include the token
const safeFetch = createProtectedFetch();
const response = await safeFetch('/api/submit', { method: 'POST', body: data });
```

### Server-Side Verification

```python
import requests

token = request.headers.get('X-H33-BotShield-Token')
result = requests.post('https://api.h33.ai/v1/botshield/verify',
    json={"session_token": token})

if result.json()["valid"]:
    # Human — process request
else:
    # No valid proof — reject
```

## How It Works

1. **Challenge** — Server issues a random nonce + difficulty level
2. **Prove** — Browser solves SHA-256 proof of work using Web Crypto API (non-blocking)
3. **Verify** — Server checks solution in microseconds, issues session token
4. **Protected** — Every subsequent request carries the token

## Why Not CAPTCHA?

| | reCAPTCHA | hCaptcha | Turnstile | **BotShield** |
|---|---|---|---|---|
| Tracks users | Yes (Google) | Yes | Proprietary | **No** |
| User friction | High | High | Low | **Zero** |
| Accessible | No | No | Partial | **Yes** |
| Third-party | Google | hCaptcha | Cloudflare | **None** |
| GDPR compliant | No | Partial | Partial | **Yes** |

## Configuration

```javascript
import { protect } from '@h33/botshield';

await protect({
  baseUrl: 'https://api.h33.ai',  // API endpoint
  badge: true,                      // Show "Secured by H33.ai" (free tier)
  onVerified: (token) => {          // Callback on success
    console.log('Verified:', token);
  },
  onError: (err) => {               // Callback on failure
    console.error('BotShield error:', err);
  }
});
```

## API

### `protect(options?)` → `Promise<string>`
Full protection flow. Returns the session token.

### `solve(nonce, difficulty)` → `Promise<number>`
Solve a PoW challenge. Returns the solution.

### `requestChallenge(baseUrl?, options?)` → `Promise<object>`
Request a challenge from the server.

### `submitSolution(baseUrl?, solution)` → `Promise<object>`
Submit a solved challenge.

### `verifyToken(baseUrl?, token)` → `Promise<object>`
Verify a session token.

### `getToken()` → `string | null`
Get the current session token.

### `createProtectedFetch(originalFetch?)` → `function`
Wrap fetch to auto-include the BotShield token header.

## Pricing

- **Free**: 10,000 challenges/month. Badge displayed.
- **Pro** ($49/mo): Unlimited challenges. Badge removed.

## License

MIT

---

Built by [H33.ai](https://h33.ai) — Post-Quantum Encryption Platform