@dupecom/botcha 0.4.6 → 0.6.0

package/README.md

@@ -53,15 +53,91 @@ app.listen(3000);
 
 ## 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:
 
-- ✅ **AI agents** compute hashes instantly
-- ❌ **Humans** can't copy-paste fast enough
+### 🔥 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
+```
+
+## 🔄 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
+```
+
+### 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..."}
 ```
-Challenge: [645234, 891023, 334521, 789012, 456789]
-Task: SHA256 each number, return first 8 hex chars
-Time limit: 500ms```
+
+**API Endpoints:**
+- `GET /v1/challenge/stream` - Open SSE connection
+- `POST /v1/challenge/stream/:session` - Send actions (go, solve)
 
 ## 🤖 AI Agent Discovery
 
@@ -81,9 +157,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 +171,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 +222,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

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
  *

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,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"}

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';
+// Export stream client
+export { BotchaStreamClient } from './stream.js';
 /**
  * BOTCHA Client SDK for AI Agents
  *

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

@@ -53,4 +53,35 @@ export interface TokenResponse {
     };
     nextStep?: string;
 }
+/**
+ * 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":"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;AAED;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;IAClE,IAAI,EAAE,GAAG,CAAC;CACX;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,wCAAwC;IACxC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;IACpE,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

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.4.6",
+  "version": "0.6.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",