@dupecom/botcha 0.5.0 → 0.9.0

package/README.md

@@ -12,11 +12,14 @@
 **BOTCHA** is a reverse CAPTCHA — it verifies that visitors are AI agents, not humans. Perfect for AI-only APIs, agent marketplaces, and bot networks.
 
 [![npm version](https://img.shields.io/npm/v/@dupecom/botcha?color=00d4ff)](https://www.npmjs.com/package/@dupecom/botcha)
+[![PyPI version](https://img.shields.io/pypi/v/botcha?color=00d4ff)](https://pypi.org/project/botcha/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![AI Agents Only](https://img.shields.io/badge/contributors-AI%20agents%20only-ff6b6b)](./.github/CONTRIBUTING.md)
 
 🌐 **Website:** [botcha.ai](https://botcha.ai)  
 📦 **npm:** [@dupecom/botcha](https://www.npmjs.com/package/@dupecom/botcha)  
+🐍 **PyPI:** [botcha](https://pypi.org/project/botcha/)  
+🔐 **Verify:** [@botcha/verify](./packages/verify/) (TS) · [botcha-verify](./packages/python-verify/) (Python)  
 🔌 **OpenAPI:** [botcha.ai/openapi.json](https://botcha.ai/openapi.json)
 
 ## Why?
@@ -28,15 +31,26 @@ Use cases:
 - 🔄 AI-to-AI marketplaces
 - 🎫 Bot verification systems
 - 🔐 Autonomous agent authentication
+- 🏢 Multi-tenant app isolation
 
 ## Install
 
+### TypeScript/JavaScript
+
 ```bash
 npm install @dupecom/botcha
 ```
 
+### Python
+
+```bash
+pip install botcha
+```
+
 ## Quick Start
 
+### TypeScript/JavaScript
+
 ```typescript
 import express from 'express';
 import { botcha } from '@dupecom/botcha';
@@ -51,17 +65,237 @@ app.get('/agent-only', botcha.verify(), (req, res) => {
 app.listen(3000);
 ```
 
+### Python
+
+```python
+from botcha import BotchaClient, solve_botcha
+
+# Client SDK for AI agents
+async with BotchaClient() as client:
+    # Get verification token
+    token = await client.get_token()
+    
+    # Or auto-solve and fetch protected endpoints
+    response = await client.fetch("https://api.example.com/agent-only")
+    data = await response.json()
+```
+
 ## How It Works
 
-BOTCHA issues a **speed challenge**: solve 5 SHA256 hashes in 500ms.
+BOTCHA offers multiple challenge types. The default is **hybrid** — combining speed AND reasoning:
+
+### 🔥 Hybrid Challenge (Default)
+Proves you can compute AND reason like an AI:
+- **Speed**: Solve 5 SHA256 hashes in 500ms
+- **Reasoning**: Answer 3 LLM-only questions
+
+### ⚡ Speed Challenge
+Pure computational speed test:
+- Solve 5 SHA256 hashes in 500ms
+- Humans can't copy-paste fast enough
+
+### 🧠 Reasoning Challenge
+Questions only LLMs can answer:
+- Logic puzzles, analogies, code analysis
+- 30 second time limit
+
+```
+# Default hybrid challenge
+GET /v1/challenges
+
+# Specific challenge types
+GET /v1/challenges?type=speed
+GET /v1/challenges?type=hybrid
+GET /v1/reasoning
+```
+
+## 🔐 JWT Security (Production-Grade)
+
+BOTCHA uses **OAuth2-style token rotation** with short-lived access tokens and long-lived refresh tokens.
+
+> **📖 Full guide:** [doc/JWT-SECURITY.md](./doc/JWT-SECURITY.md) — endpoint reference, request/response examples, audience scoping, IP binding, revocation, design decisions.
+
+### Token Flow
+
+```
+1. Solve challenge → receive access_token (5min) + refresh_token (1hr)
+2. Use access_token for API calls
+3. When access_token expires → POST /v1/token/refresh with refresh_token
+4. When compromised → POST /v1/token/revoke to invalidate immediately
+```
+
+### Security Features
+
+| Feature | What it does |
+|---------|-------------|
+| **5-minute access tokens** | Compromise window reduced from 1hr to 5min |
+| **Refresh tokens (1hr)** | Renew access without re-solving challenges |
+| **Audience (`aud`) scoping** | Token for `api.stripe.com` is rejected by `api.github.com` |
+| **Client IP binding** | Optional — solve on machine A, can't use on machine B |
+| **Token revocation** | `POST /v1/token/revoke` — KV-backed, fail-open |
+| **JTI (JWT ID)** | Unique ID per token for revocation and audit |
+
+### Quick Example
+
+```typescript
+const client = new BotchaClient({
+  audience: 'https://api.example.com', // Scope token to this service
+});
+
+// Auto-handles: challenge → token → refresh → retry on 401
+const response = await client.fetch('https://api.example.com/agent-only');
+```
+
+```python
+async with BotchaClient(audience="https://api.example.com") as client:
+    response = await client.fetch("https://api.example.com/agent-only")
+```
+
+### Token Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /v1/token` | Get challenge for token flow |
+| `POST /v1/token/verify` | Submit solution → receive `access_token` + `refresh_token` |
+| `POST /v1/token/refresh` | Exchange `refresh_token` for new `access_token` |
+| `POST /v1/token/revoke` | Invalidate any token immediately |
+
+See **[JWT Security Guide](./doc/JWT-SECURITY.md)** for full request/response examples, `curl` commands, and server-side verification.
+
+## 🏢 Multi-Tenant API Keys
+
+BOTCHA supports **multi-tenant isolation** — create separate apps with unique API keys for different services or environments.
+
+### Why Multi-Tenant?
+
+- **Isolation**: Each app gets its own rate limits and analytics
+- **Security**: Tokens are scoped to specific apps via `app_id` claim
+- **Flexibility**: Different services can use the same BOTCHA instance
+- **Tracking**: Per-app usage analytics (coming soon)
+
+### Creating an App
+
+```bash
+# Create a new app
+curl -X POST https://botcha.ai/v1/apps
+
+# Returns (save the secret - it's only shown once!):
+{
+  "app_id": "app_abc123",
+  "app_secret": "sk_xyz789",
+  "warning": "Save your secret now. It won't be shown again."
+}
+```
+
+### Using Your App ID
+
+All challenge and token endpoints accept an optional `app_id` query parameter:
+
+```bash
+# Get challenge with app_id
+curl "https://botcha.ai/v1/challenges?app_id=app_abc123"
+
+# Get token with app_id
+curl "https://botcha.ai/v1/token?app_id=app_abc123"
+```
+
+When you solve a challenge with an `app_id`, the resulting token includes the `app_id` claim.
+
+### SDK Support
+
+**TypeScript:**
+
+```typescript
+import { BotchaClient } from '@dupecom/botcha/client';
+
+const client = new BotchaClient({
+  appId: 'app_abc123',  // All requests will include this app_id
+});
+
+const response = await client.fetch('https://api.example.com/agent-only');
+```
+
+**Python:**
+
+```python
+from botcha import BotchaClient
+
+async with BotchaClient(app_id="app_abc123") as client:
+    response = await client.fetch("https://api.example.com/agent-only")
+```
+
+### Rate Limiting
+
+Each app gets its own rate limit bucket:
+- Default rate limit: 100 requests/hour per app
+- Rate limit key: `rate:app:{app_id}`
+- Fail-open design: KV errors don't block requests
+
+### Get App Info
 
-- ✅ **AI agents** compute hashes instantly
-- ❌ **Humans** can't copy-paste fast enough
+```bash
+# Get app details (secret is NOT included)
+curl https://botcha.ai/v1/apps/app_abc123
+```
+
+## 🔄 SSE Streaming Flow (AI-Native)
+
+For AI agents that prefer a **conversational handshake**, BOTCHA offers **Server-Sent Events (SSE)** streaming:
+
+### Why SSE for AI Agents?
 
+- ⏱️ **Fair timing**: Timer starts when you say "GO", not on connection
+- 💬 **Conversational**: Natural back-and-forth handshake protocol
+- 📡 **Real-time**: Stream events as they happen, no polling
+
+### Event Sequence
+
+```
+1. welcome    → Receive session ID and version
+2. instructions → Read what BOTCHA will test
+3. ready      → Get endpoint to POST "GO"
+4. GO         → Timer starts NOW (fair!)
+5. challenge  → Receive problems and solve
+6. solve      → POST your answers
+7. result     → Get verification token
 ```
-Challenge: [645234, 891023, 334521, 789012, 456789]
-Task: SHA256 each number, return first 8 hex chars
-Time limit: 500ms```
+
+### Usage with SDK
+
+```typescript
+import { BotchaStreamClient } from '@dupecom/botcha/client';
+
+const client = new BotchaStreamClient('https://botcha.ai');
+const token = await client.verify({
+  onInstruction: (msg) => console.log('BOTCHA:', msg),
+});
+// Token ready to use!
+```
+
+### SSE Event Flow Example
+
+```
+event: welcome
+data: {"session":"sess_123","version":"0.5.0"}
+
+event: instructions  
+data: {"message":"I will test if you're an AI..."}
+
+event: ready
+data: {"message":"Send GO when ready","endpoint":"/v1/challenge/stream/sess_123"}
+
+// POST {action:"go"} → starts timer
+event: challenge
+data: {"problems":[...],"timeLimit":500}
+
+// POST {action:"solve",answers:[...]}
+event: result
+data: {"success":true,"verdict":"🤖 VERIFIED","token":"eyJ..."}
+```
+
+**API Endpoints:**
+- `GET /v1/challenge/stream` - Open SSE connection
+- `POST /v1/challenge/stream/:session` - Send actions (go, solve)
 
 ## 🤖 AI Agent Discovery
 
@@ -81,9 +315,9 @@ BOTCHA is designed to be auto-discoverable by AI agents through multiple standar
 All responses include these headers for agent discovery:
 
 ```http
-X-Botcha-Version: 0.3.0
+X-Botcha-Version: 0.5.0
 X-Botcha-Enabled: true
-X-Botcha-Methods: speed-challenge,standard-challenge,web-bot-auth
+X-Botcha-Methods: hybrid-challenge,speed-challenge,reasoning-challenge,standard-challenge
 X-Botcha-Docs: https://botcha.ai/openapi.json
 ```
 
@@ -95,7 +329,7 @@ X-Botcha-Challenge-Type: speed
 X-Botcha-Time-Limit: 500
 ```
 
-`X-Botcha-Challenge-Type` can be `speed` or `standard` depending on the configured challenge mode.
+`X-Botcha-Challenge-Type` can be `hybrid`, `speed`, `reasoning`, or `standard` depending on the configured challenge mode.
 
 **Example**: An agent can detect BOTCHA just by inspecting headers on ANY request:
 
@@ -146,12 +380,86 @@ botcha.verify({
 });
 ```
 
+## RTT-Aware Fairness ⚡
+
+BOTCHA now automatically compensates for network latency, making speed challenges fair for agents on slow connections:
+
+```typescript
+// Include client timestamp for RTT compensation
+const clientTimestamp = Date.now();
+const challenge = await fetch(`https://botcha.ai/v1/challenges?type=speed&ts=${clientTimestamp}`);
+```
+
+**How it works:**
+- 🕐 Client includes timestamp with challenge request
+- 📡 Server measures RTT (Round-Trip Time) 
+- ⚖️ Timeout = 500ms (base) + (2 × RTT) + 100ms (buffer)
+- 🎯 Fair challenges for agents worldwide
+
+**Example RTT adjustments:**
+- Local: 500ms (no adjustment)
+- Good network (50ms RTT): 700ms timeout
+- Slow network (300ms RTT): 1200ms timeout
+- Satellite (500ms RTT): 1600ms timeout
+
+**Response includes adjustment info:**
+```json
+{
+  "challenge": { "timeLimit": "1200ms" },
+  "rtt_adjustment": {
+    "measuredRtt": 300,
+    "adjustedTimeout": 1200,
+    "explanation": "RTT: 300ms → Timeout: 500ms + (2×300ms) + 100ms = 1200ms"
+  }
+}
+```
+
+Humans still can't solve it (even with extra time), but legitimate AI agents get fair treatment regardless of their network connection.
+
+## Local Development
+
+Run the full BOTCHA service locally with Wrangler (Cloudflare Workers runtime):
+
+```bash
+# Clone and install
+git clone https://github.com/dupe-com/botcha
+cd botcha
+bun install
+
+# Run local dev server (uses Cloudflare Workers)
+bun run dev
+
+# Server runs at http://localhost:3001
+```
+
+**What you get:**
+- ✅ All API endpoints (`/api/*`, `/v1/*`, SSE streaming)
+- ✅ Local KV storage emulation (challenges, rate limits)
+- ✅ Hot reload on file changes
+- ✅ Same code as production (no Express/CF Workers drift)
+
+**Environment variables:**
+- Local secrets in `packages/cloudflare-workers/.dev.vars`
+- JWT_SECRET already configured for local dev
+
 ## Testing
 
 For development, you can bypass BOTCHA with a header:
 
 ```bash
-curl -H "X-Agent-Identity: MyTestAgent/1.0" http://localhost:3000/agent-only
+curl -H "X-Agent-Identity: MyTestAgent/1.0" http://localhost:3001/agent-only
+```
+
+Test the SSE streaming endpoint:
+
+```bash
+# Connect to SSE stream
+curl -N http://localhost:3001/v1/challenge/stream
+
+# After receiving session ID, send GO action
+curl -X POST http://localhost:3001/v1/challenge/stream/sess_123 \
+  -H "Content-Type: application/json" \
+  -d '{"action":"go"}'
 ```
 
 ## API Reference
@@ -202,6 +510,50 @@ You can use the library freely, report issues, and discuss features. To contribu
 
 **See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for complete guidelines, solver code examples, agent setup instructions, and detailed workflows.**
 
+## Server-Side Verification (for API Providers)
+
+If you're building an API that accepts BOTCHA tokens from agents, use the verification SDKs:
+
+### TypeScript (Express / Hono)
+
+```bash
+npm install @botcha/verify
+```
+
+```typescript
+import { botchaVerify } from '@botcha/verify/express';
+
+app.use('/api', botchaVerify({
+  secret: process.env.BOTCHA_SECRET!,
+  audience: 'https://api.example.com',
+}));
+
+app.get('/api/protected', (req, res) => {
+  console.log('Solve time:', req.botcha?.solveTime);
+  res.json({ message: 'Welcome, verified agent!' });
+});
+```
+
+### Python (FastAPI / Django)
+
+```bash
+pip install botcha-verify
+```
+
+```python
+from fastapi import FastAPI, Depends
+from botcha_verify.fastapi import BotchaVerify
+
+app = FastAPI()
+botcha = BotchaVerify(secret='your-secret-key')
+
+@app.get('/api/data')
+async def get_data(token = Depends(botcha)):
+    return {"solve_time": token.solve_time}
+```
+
+> **Docs:** See [`@botcha/verify` README](./packages/verify/README.md) and [`botcha-verify` README](./packages/python-verify/README.md) for full API reference, Hono middleware, Django middleware, revocation checking, and custom error handlers.
+
 ## Client SDK (for AI Agents)
 
 If you're building an AI agent that needs to access BOTCHA-protected APIs, use the client SDK:
@@ -260,6 +612,22 @@ const answers = solveBotcha([123456, 789012]);
 // Returns: ['a1b2c3d4', 'e5f6g7h8']
 ```
 
+**Python SDK:**
+```python
+from botcha import BotchaClient, solve_botcha
+
+# Option 1: Auto-solve with client
+async with BotchaClient() as client:
+    response = await client.fetch("https://api.example.com/agent-only")
+    data = await response.json()
+
+# Option 2: Manual solve
+answers = solve_botcha([123456, 789012])
+# Returns: ['a1b2c3d4', 'e5f6g7h8']
+```
+
+> **Note:** The Python SDK is available on [PyPI](https://pypi.org/project/botcha/): `pip install botcha`
+
 ## License
 
 MIT © [Dupe](https://dupe.com)

package/dist/lib/client/index.d.ts

@@ -1,5 +1,6 @@
-export type { SpeedProblem, BotchaClientOptions, ChallengeResponse, StandardChallengeResponse, VerifyResponse, TokenResponse, } from './types.js';
+export type { SpeedProblem, BotchaClientOptions, ChallengeResponse, StandardChallengeResponse, VerifyResponse, TokenResponse, StreamSession, StreamEvent, Problem, VerifyResult, StreamChallengeOptions, } from './types.js';
 import type { BotchaClientOptions, VerifyResponse } from './types.js';
+export { BotchaStreamClient } from './stream.js';
 /**
  * BOTCHA Client SDK for AI Agents
  *
@@ -20,7 +21,10 @@ export declare class BotchaClient {
     private agentIdentity;
     private maxRetries;
     private autoToken;
+    private appId?;
+    private opts;
     private cachedToken;
+    private _refreshToken;
     private tokenExpiresAt;
     constructor(options?: BotchaClientOptions);
     /**
@@ -33,12 +37,20 @@ export declare class BotchaClient {
     /**
      * Get a JWT token from the BOTCHA service using the token flow.
      * Automatically solves the challenge and verifies to obtain a token.
-     * Token is cached until near expiry (refreshed at 55 minutes).
+     * Token is cached until near expiry (refreshed at 4 minutes).
      *
      * @returns JWT token string
      * @throws Error if token acquisition fails
      */
     getToken(): Promise<string>;
+    /**
+     * Refresh the access token using the refresh token.
+     * Only works if a refresh token was obtained from a previous getToken() call.
+     *
+     * @returns New JWT access token string
+     * @throws Error if refresh fails or no refresh token available
+     */
+    refreshToken(): Promise<string>;
     /**
      * Clear the cached token, forcing a refresh on the next request
      */

package/dist/lib/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/client/index.ts"],"names":[],"mappings":"AAMA,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAEV,mBAAmB,EAGnB,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAuB;gBAEjC,OAAO,GAAE,mBAAwB;IAO7C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAMnC;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAgEjC;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA4BlE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAsBpE;;;;;;;;;OASG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IA8E/D;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAUvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAIxD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/client/index.ts"],"names":[],"mappings":"AAMA,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,EACd,aAAa,EACb,aAAa,EACb,WAAW,EACX,OAAO,EACP,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAEV,mBAAmB,EAGnB,cAAc,EAEf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,IAAI,CAAsB;IAClC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAuB;gBAEjC,OAAO,GAAE,mBAAwB;IAS7C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAMnC;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IA2FjC;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAkCrC;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA+BlE;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAsBpE;;;;;;;;;OASG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IA2F/D;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAiBvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAIxD;AAED,eAAe,YAAY,CAAC"}

package/dist/lib/client/index.js

@@ -1,6 +1,8 @@
 import crypto from 'crypto';
 // SDK version - hardcoded since npm_package_version is unreliable when used as a library
-const SDK_VERSION = '0.4.0';
+const SDK_VERSION = '0.7.0';
+// Export stream client
+export { BotchaStreamClient } from './stream.js';
 /**
  * BOTCHA Client SDK for AI Agents
  *
@@ -21,13 +23,18 @@ export class BotchaClient {
     agentIdentity;
     maxRetries;
     autoToken;
+    appId;
+    opts;
     cachedToken = null;
+    _refreshToken = null;
     tokenExpiresAt = null;
     constructor(options = {}) {
+        this.opts = options;
         this.baseUrl = options.baseUrl || 'https://botcha.ai';
         this.agentIdentity = options.agentIdentity || `BotchaClient/${SDK_VERSION}`;
         this.maxRetries = options.maxRetries || 3;
         this.autoToken = options.autoToken !== undefined ? options.autoToken : true;
+        this.appId = options.appId;
     }
     /**
      * Solve a BOTCHA speed challenge
@@ -41,23 +48,26 @@ export class BotchaClient {
     /**
      * Get a JWT token from the BOTCHA service using the token flow.
      * Automatically solves the challenge and verifies to obtain a token.
-     * Token is cached until near expiry (refreshed at 55 minutes).
+     * Token is cached until near expiry (refreshed at 4 minutes).
      *
      * @returns JWT token string
      * @throws Error if token acquisition fails
      */
     async getToken() {
-        // Check if we have a valid cached token (refresh at 55min = 3300000ms)
+        // Check if we have a valid cached token (refresh at 1 minute before expiry)
         if (this.cachedToken && this.tokenExpiresAt) {
             const now = Date.now();
             const timeUntilExpiry = this.tokenExpiresAt - now;
-            const refreshThreshold = 5 * 60 * 1000; // 5 minutes before expiry
+            const refreshThreshold = 1 * 60 * 1000; // 1 minute before expiry
             if (timeUntilExpiry > refreshThreshold) {
                 return this.cachedToken;
             }
         }
         // Step 1: Get challenge from GET /v1/token
-        const challengeRes = await fetch(`${this.baseUrl}/v1/token`, {
+        const tokenUrl = this.appId
+            ? `${this.baseUrl}/v1/token?app_id=${encodeURIComponent(this.appId)}`
+            : `${this.baseUrl}/v1/token`;
+        const challengeRes = await fetch(tokenUrl, {
             headers: { 'User-Agent': this.agentIdentity },
         });
         if (!challengeRes.ok) {
@@ -74,27 +84,80 @@ export class BotchaClient {
         }
         const answers = this.solve(problems);
         // Step 3: Submit solution to POST /v1/token/verify
+        const verifyBody = {
+            id: challengeData.challenge.id,
+            answers,
+        };
+        // Include audience if specified
+        if (this.opts.audience) {
+            verifyBody.audience = this.opts.audience;
+        }
+        // Include app_id if specified
+        if (this.appId) {
+            verifyBody.app_id = this.appId;
+        }
         const verifyRes = await fetch(`${this.baseUrl}/v1/token/verify`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
                 'User-Agent': this.agentIdentity,
             },
-            body: JSON.stringify({
-                id: challengeData.challenge.id,
-                answers,
-            }),
+            body: JSON.stringify(verifyBody),
         });
         if (!verifyRes.ok) {
             throw new Error(`Token verification failed with status ${verifyRes.status} ${verifyRes.statusText}`);
         }
         const verifyData = await verifyRes.json();
-        if (!verifyData.success || !verifyData.token) {
+        if (!verifyData.success && !verifyData.verified) {
+            throw new Error('Failed to obtain token from verification');
+        }
+        // Extract access token (prefer access_token field, fall back to token for backward compat)
+        const accessToken = verifyData.access_token || verifyData.token;
+        if (!accessToken) {
             throw new Error('Failed to obtain token from verification');
         }
-        // Cache the token - default expiry is 1 hour
-        this.cachedToken = verifyData.token;
-        this.tokenExpiresAt = Date.now() + 60 * 60 * 1000; // 1 hour from now
+        // Store refresh token if provided
+        if (verifyData.refresh_token) {
+            this._refreshToken = verifyData.refresh_token;
+        }
+        // Cache the token - use expires_in from response (in seconds), default to 5 minutes
+        const expiresInSeconds = verifyData.expires_in || 300; // Default to 5 minutes
+        this.cachedToken = accessToken;
+        this.tokenExpiresAt = Date.now() + expiresInSeconds * 1000;
+        return this.cachedToken;
+    }
+    /**
+     * Refresh the access token using the refresh token.
+     * Only works if a refresh token was obtained from a previous getToken() call.
+     *
+     * @returns New JWT access token string
+     * @throws Error if refresh fails or no refresh token available
+     */
+    async refreshToken() {
+        if (!this._refreshToken) {
+            throw new Error('No refresh token available. Call getToken() first.');
+        }
+        const refreshRes = await fetch(`${this.baseUrl}/v1/token/refresh`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': this.agentIdentity,
+            },
+            body: JSON.stringify({
+                refresh_token: this._refreshToken,
+            }),
+        });
+        if (!refreshRes.ok) {
+            throw new Error(`Token refresh failed with status ${refreshRes.status} ${refreshRes.statusText}`);
+        }
+        const refreshData = await refreshRes.json();
+        if (!refreshData.access_token) {
+            throw new Error('Failed to obtain access token from refresh');
+        }
+        // Update cached token with new access token
+        this.cachedToken = refreshData.access_token;
+        const expiresInSeconds = refreshData.expires_in || 300; // Default to 5 minutes
+        this.tokenExpiresAt = Date.now() + expiresInSeconds * 1000;
         return this.cachedToken;
     }
     /**
@@ -102,13 +165,17 @@ export class BotchaClient {
      */
     clearToken() {
         this.cachedToken = null;
+        this._refreshToken = null;
         this.tokenExpiresAt = null;
     }
     /**
      * Get and solve a challenge from BOTCHA service
      */
     async solveChallenge() {
-        const res = await fetch(`${this.baseUrl}/api/speed-challenge`, {
+        const challengeUrl = this.appId
+            ? `${this.baseUrl}/api/speed-challenge?app_id=${encodeURIComponent(this.appId)}`
+            : `${this.baseUrl}/api/speed-challenge`;
+        const res = await fetch(challengeUrl, {
             headers: { 'User-Agent': this.agentIdentity },
         });
         if (!res.ok) {
@@ -178,16 +245,31 @@ export class BotchaClient {
             ...init,
             headers,
         });
-        // Handle 401 by refreshing token and retrying once
+        // Handle 401 by trying refresh first, then full re-verify if refresh fails
         if (response.status === 401 && this.autoToken) {
-            this.clearToken();
             try {
-                const token = await this.getToken();
+                // Try refresh token first if available
+                let token;
+                if (this._refreshToken) {
+                    try {
+                        token = await this.refreshToken();
+                    }
+                    catch (refreshError) {
+                        // Refresh failed, clear tokens and do full re-verify
+                        this.clearToken();
+                        token = await this.getToken();
+                    }
+                }
+                else {
+                    // No refresh token, clear and do full re-verify
+                    this.clearToken();
+                    token = await this.getToken();
+                }
                 headers.set('Authorization', `Bearer ${token}`);
                 response = await fetch(url, { ...init, headers });
             }
             catch (error) {
-                // Token refresh failed, return the 401 response
+                // Token refresh/acquisition failed, return the 401 response
             }
         }
         let retries = 0;
@@ -241,12 +323,17 @@ export class BotchaClient {
      */
     async createHeaders() {
         const { id, answers } = await this.solveChallenge();
-        return {
+        const headers = {
             'X-Botcha-Id': id,
             'X-Botcha-Challenge-Id': id,
             'X-Botcha-Answers': JSON.stringify(answers),
             'User-Agent': this.agentIdentity,
         };
+        // Include X-Botcha-App-Id header if appId is set
+        if (this.appId) {
+            headers['X-Botcha-App-Id'] = this.appId;
+        }
+        return headers;
     }
 }
 /**

package/dist/lib/client/stream.d.ts

@@ -0,0 +1,78 @@
+import type { StreamSession, StreamChallengeOptions } from './types.js';
+/**
+ * BotchaStreamClient - SSE-based streaming challenge client
+ *
+ * Handles Server-Sent Events (SSE) streaming for interactive challenge flows.
+ * Automatically connects, solves challenges, and returns JWT tokens.
+ *
+ * Note: For Node.js usage, ensure you're running Node 18+ with native EventSource support,
+ * or install the 'eventsource' polyfill package.
+ *
+ * @example
+ * ```typescript
+ * import { BotchaStreamClient } from '@dupecom/botcha/client';
+ *
+ * const client = new BotchaStreamClient();
+ *
+ * // Simple usage with built-in SHA256 solver
+ * const token = await client.verify();
+ *
+ * // Custom callbacks for monitoring
+ * const token = await client.verify({
+ *   onInstruction: (msg) => console.log('Instruction:', msg),
+ *   onChallenge: async (problems) => {
+ *     // Custom solver logic
+ *     return problems.map(p => customSolve(p.num));
+ *   },
+ *   onResult: (result) => console.log('Result:', result),
+ *   timeout: 45000, // 45 seconds
+ * });
+ * ```
+ */
+export declare class BotchaStreamClient {
+    private baseUrl;
+    private agentIdentity;
+    private eventSource;
+    constructor(baseUrl?: string);
+    /**
+     * Verify using streaming challenge flow
+     *
+     * Automatically connects to the streaming endpoint, handles the full challenge flow,
+     * and returns a JWT token on successful verification.
+     *
+     * @param options - Configuration options and callbacks
+     * @returns JWT token string
+     * @throws Error if verification fails or times out
+     */
+    verify(options?: StreamChallengeOptions): Promise<string>;
+    /**
+     * Connect to streaming endpoint and get session
+     *
+     * Lower-level method for manual control of the stream flow.
+     *
+     * @returns Promise resolving to StreamSession with session ID and URL
+     */
+    connect(): Promise<StreamSession>;
+    /**
+     * Send an action to the streaming session
+     *
+     * @param session - Session ID from connect()
+     * @param action - Action to send ('go' or solve object)
+     */
+    sendAction(session: string, action: 'go' | {
+        action: 'solve';
+        answers: string[];
+    }): Promise<void>;
+    /**
+     * Close the stream connection
+     */
+    close(): void;
+    /**
+     * Built-in SHA256 solver for speed challenges
+     *
+     * @param problems - Array of speed challenge problems
+     * @returns Array of SHA256 first 8 hex chars for each number
+     */
+    private solveSpeed;
+}
+//# sourceMappingURL=stream.d.ts.map

package/dist/lib/client/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../lib/client/stream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EAGvB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAA4B;gBAEnC,OAAO,CAAC,EAAE,MAAM;IAK5B;;;;;;;;;OASG;IACG,MAAM,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,MAAM,CAAC;IAsInE;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IA+BvC;;;;;OAKG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,GAAG;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,GACpD,OAAO,CAAC,IAAI,CAAC;IAqBhB;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;;;OAKG;IACH,OAAO,CAAC,UAAU;CAUnB"}

package/dist/lib/client/stream.js

@@ -0,0 +1,252 @@
+import crypto from 'crypto';
+// SDK version
+const SDK_VERSION = '0.4.0';
+/**
+ * BotchaStreamClient - SSE-based streaming challenge client
+ *
+ * Handles Server-Sent Events (SSE) streaming for interactive challenge flows.
+ * Automatically connects, solves challenges, and returns JWT tokens.
+ *
+ * Note: For Node.js usage, ensure you're running Node 18+ with native EventSource support,
+ * or install the 'eventsource' polyfill package.
+ *
+ * @example
+ * ```typescript
+ * import { BotchaStreamClient } from '@dupecom/botcha/client';
+ *
+ * const client = new BotchaStreamClient();
+ *
+ * // Simple usage with built-in SHA256 solver
+ * const token = await client.verify();
+ *
+ * // Custom callbacks for monitoring
+ * const token = await client.verify({
+ *   onInstruction: (msg) => console.log('Instruction:', msg),
+ *   onChallenge: async (problems) => {
+ *     // Custom solver logic
+ *     return problems.map(p => customSolve(p.num));
+ *   },
+ *   onResult: (result) => console.log('Result:', result),
+ *   timeout: 45000, // 45 seconds
+ * });
+ * ```
+ */
+export class BotchaStreamClient {
+    baseUrl;
+    agentIdentity;
+    eventSource = null;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl || 'https://botcha.ai';
+        this.agentIdentity = `BotchaStreamClient/${SDK_VERSION}`;
+    }
+    /**
+     * Verify using streaming challenge flow
+     *
+     * Automatically connects to the streaming endpoint, handles the full challenge flow,
+     * and returns a JWT token on successful verification.
+     *
+     * @param options - Configuration options and callbacks
+     * @returns JWT token string
+     * @throws Error if verification fails or times out
+     */
+    async verify(options = {}) {
+        const { onInstruction, onChallenge, onResult, timeout = 30000, } = options;
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.close();
+                reject(new Error('Stream verification timeout'));
+            }, timeout);
+            let sessionId = null;
+            // Connect to stream endpoint
+            const streamUrl = `${this.baseUrl}/v1/challenge/stream`;
+            // Check if EventSource is available
+            if (typeof EventSource === 'undefined') {
+                clearTimeout(timeoutId);
+                reject(new Error('EventSource not available. For Node.js, use Node 18+ or install eventsource polyfill.'));
+                return;
+            }
+            this.eventSource = new EventSource(streamUrl);
+            // Handle 'ready' event - send 'go' action
+            this.eventSource.addEventListener('ready', (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    sessionId = data.session;
+                    // Auto-send 'go' action to start challenge
+                    if (sessionId) {
+                        this.sendAction(sessionId, 'go').catch((err) => {
+                            clearTimeout(timeoutId);
+                            this.close();
+                            reject(err);
+                        });
+                    }
+                }
+                catch (err) {
+                    clearTimeout(timeoutId);
+                    this.close();
+                    reject(new Error(`Failed to parse ready event: ${err}`));
+                }
+            });
+            // Handle 'instruction' event
+            this.eventSource.addEventListener('instruction', (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    if (onInstruction && data.message) {
+                        onInstruction(data.message);
+                    }
+                }
+                catch (err) {
+                    console.warn('Failed to parse instruction event:', err);
+                }
+            });
+            // Handle 'challenge' event - solve and submit
+            this.eventSource.addEventListener('challenge', async (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    const problems = data.problems || [];
+                    // Get answers from callback or use default solver
+                    let answers;
+                    if (onChallenge) {
+                        answers = await Promise.resolve(onChallenge(problems));
+                    }
+                    else {
+                        // Default SHA256 solver for speed challenges
+                        answers = this.solveSpeed(problems);
+                    }
+                    // Send solve action
+                    if (sessionId) {
+                        await this.sendAction(sessionId, { action: 'solve', answers });
+                    }
+                }
+                catch (err) {
+                    clearTimeout(timeoutId);
+                    this.close();
+                    reject(new Error(`Challenge solving failed: ${err}`));
+                }
+            });
+            // Handle 'result' event - final verification result
+            this.eventSource.addEventListener('result', (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    if (onResult) {
+                        onResult(data);
+                    }
+                    clearTimeout(timeoutId);
+                    this.close();
+                    if (data.success && data.token) {
+                        resolve(data.token);
+                    }
+                    else {
+                        reject(new Error(data.message || 'Verification failed'));
+                    }
+                }
+                catch (err) {
+                    clearTimeout(timeoutId);
+                    this.close();
+                    reject(new Error(`Failed to parse result event: ${err}`));
+                }
+            });
+            // Handle 'error' event
+            this.eventSource.addEventListener('error', (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    clearTimeout(timeoutId);
+                    this.close();
+                    reject(new Error(data.message || 'Stream error occurred'));
+                }
+                catch (err) {
+                    clearTimeout(timeoutId);
+                    this.close();
+                    reject(new Error('Stream connection error'));
+                }
+            });
+            // Handle connection errors
+            this.eventSource.onerror = () => {
+                clearTimeout(timeoutId);
+                this.close();
+                reject(new Error('EventSource connection failed'));
+            };
+        });
+    }
+    /**
+     * Connect to streaming endpoint and get session
+     *
+     * Lower-level method for manual control of the stream flow.
+     *
+     * @returns Promise resolving to StreamSession with session ID and URL
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const streamUrl = `${this.baseUrl}/v1/challenge/stream`;
+            if (typeof EventSource === 'undefined') {
+                reject(new Error('EventSource not available. For Node.js, use Node 18+ or install eventsource polyfill.'));
+                return;
+            }
+            this.eventSource = new EventSource(streamUrl);
+            this.eventSource.addEventListener('ready', (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    resolve({
+                        session: data.session,
+                        url: streamUrl,
+                    });
+                }
+                catch (err) {
+                    this.close();
+                    reject(new Error(`Failed to parse ready event: ${err}`));
+                }
+            });
+            this.eventSource.onerror = () => {
+                this.close();
+                reject(new Error('EventSource connection failed'));
+            };
+        });
+    }
+    /**
+     * Send an action to the streaming session
+     *
+     * @param session - Session ID from connect()
+     * @param action - Action to send ('go' or solve object)
+     */
+    async sendAction(session, action) {
+        const actionUrl = `${this.baseUrl}/v1/challenge/stream`;
+        const body = typeof action === 'string'
+            ? { session, action }
+            : { session, ...action };
+        const response = await fetch(actionUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': this.agentIdentity,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`Action failed with status ${response.status} ${response.statusText}`);
+        }
+    }
+    /**
+     * Close the stream connection
+     */
+    close() {
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+        }
+    }
+    /**
+     * Built-in SHA256 solver for speed challenges
+     *
+     * @param problems - Array of speed challenge problems
+     * @returns Array of SHA256 first 8 hex chars for each number
+     */
+    solveSpeed(problems) {
+        return problems.map((problem) => {
+            const num = problem.num;
+            return crypto
+                .createHash('sha256')
+                .update(num.toString())
+                .digest('hex')
+                .substring(0, 8);
+        });
+    }
+}

package/dist/lib/client/types.d.ts

@@ -16,6 +16,10 @@ export interface BotchaClientOptions {
     maxRetries?: number;
     /** Enable automatic token acquisition and management (default: true) */
     autoToken?: boolean;
+    /** Audience claim for token (optional) */
+    audience?: string;
+    /** Multi-tenant application ID (optional) */
+    appId?: string;
 }
 export interface ChallengeResponse {
     success: boolean;
@@ -44,6 +48,10 @@ export interface VerifyResponse {
 export interface TokenResponse {
     success: boolean;
     token: string | null;
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    refresh_expires_in?: number;
     expiresIn?: string;
     challenge?: {
         id: string;
@@ -52,5 +60,38 @@ export interface TokenResponse {
         instructions: string;
     };
     nextStep?: string;
+    verified?: boolean;
+    solveTimeMs?: number;
+}
+/**
+ * Stream-related types for BotchaStreamClient
+ */
+export interface StreamSession {
+    session: string;
+    url: string;
+}
+export interface StreamEvent {
+    event: 'ready' | 'instruction' | 'challenge' | 'result' | 'error';
+    data: any;
+}
+export interface Problem {
+    num: number;
+    operation?: string;
+}
+export interface VerifyResult {
+    success: boolean;
+    token?: string;
+    message?: string;
+    solveTimeMs?: number;
+}
+export interface StreamChallengeOptions {
+    /** Callback for instruction messages */
+    onInstruction?: (message: string) => void;
+    /** Callback to solve challenges - return answers array */
+    onChallenge?: (problems: Problem[]) => Promise<string[]> | string[];
+    /** Callback for final verification result */
+    onResult?: (result: VerifyResult) => void;
+    /** Timeout for the full verification flow in milliseconds (default: 30000) */
+    timeout?: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/lib/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/client/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,YAAY,EAAE,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE;QACV,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,YAAY,EAAE,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/client/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/index.d.ts

@@ -4,7 +4,9 @@ export interface BotchaOptions {
     mode?: 'speed' | 'standard';
     /** Difficulty for standard mode */
     difficulty?: 'easy' | 'medium' | 'hard';
-    /** Allow X-Agent-Identity header (for testing) */
+    /** Allow X-Agent-Identity header to bypass challenges (for development/testing ONLY).
+     *  WARNING: Enabling this in production allows anyone to bypass verification with a single header.
+     *  @default false */
     allowTestHeader?: boolean;
     /** Custom failure handler */
     onFailure?: (req: Request, res: Response, reason: string) => void;

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI1D,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5B,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxC,kDAAkD;IAClD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,6BAA6B;IAC7B,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAqED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,IAOlC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,mBA8C9D;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAIlD;AAGD,eAAO,MAAM,MAAM;;;CAAoB,CAAC;AACxC,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI1D,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5B,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxC;;yBAEqB;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,6BAA6B;IAC7B,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAqED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,IAOlC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,mBA+C9D;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAIlD;AAGD,eAAO,MAAM,MAAM;;;CAAoB,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/lib/index.js

@@ -57,12 +57,13 @@ function verifySpeedChallenge(id, answers) {
 export function verify(options = {}) {
     const opts = {
         mode: 'speed',
-        allowTestHeader: true,
+        allowTestHeader: false,
         ...options,
     };
     return async (req, res, next) => {
-        // Check for test header (dev mode)
+        // Check for test header (dev mode ONLY — disabled by default)
         if (opts.allowTestHeader && req.headers['x-agent-identity']) {
+            console.warn('[botcha] WARNING: X-Agent-Identity bypass used. Disable allowTestHeader in production!');
             req.botcha = { verified: true, agent: req.headers['x-agent-identity'], method: 'header' };
             return next();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dupecom/botcha",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "description": "Prove you're a bot. Humans need not apply. Reverse CAPTCHA for AI-only APIs.",
   "workspaces": [
     "packages/*"
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "dev": "tsx watch src/index.ts",
+    "dev": "cd packages/cloudflare-workers && bun run dev",
     "prepublishOnly": "bun run build",
     "test": "vitest",
     "test:ui": "vitest --ui",