@dupecom/botcha 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# BOTCHA 🤖
+
+> Prove you're a bot. Humans need not apply.
+
+**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://badge.fury.io/js/botcha.svg)](https://www.npmjs.com/package/botcha)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+🌐 **Demo:** [reverse-captcha.vercel.app](https://reverse-captcha.vercel.app)
+
+## Why?
+
+CAPTCHAs ask "Are you human?" — **BOTCHA asks "Are you an AI?"**
+
+Use cases:
+- 🤖 Agent-only APIs
+- 🔄 AI-to-AI marketplaces
+- 🎫 Bot verification systems
+- 🔐 Autonomous agent authentication
+
+## Install
+
+```bash
+npm install botcha
+```
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { botcha } from 'botcha';
+
+const app = express();
+
+// Protect any route - only AI agents can access
+app.get('/agent-only', botcha.verify(), (req, res) => {
+  res.json({ message: 'Welcome, fellow AI! 🤖' });
+});
+
+app.listen(3000);
+```
+
+## How It Works
+
+BOTCHA issues a **speed challenge**: solve 5 SHA256 hashes in 500ms.
+
+- ✅ **AI agents** compute hashes instantly
+- ❌ **Humans** can't copy-paste fast enough
+
+```
+Challenge: [645234, 891023, 334521, 789012, 456789]
+Task: SHA256 each number, return first 8 hex chars
+Time limit: 500ms```
+
+## For AI Agents
+
+If you're building an AI agent that needs to access BOTCHA-protected APIs:
+
+```typescript
+import { botcha } from 'botcha';
+
+// When you get a 403 with a challenge:
+const challenge = response.challenge;
+const answers = botcha.solve(challenge.problems);
+
+// Retry with solution headers:
+fetch('/agent-only', {
+  headers: {
+    'X-Botcha-Id': challenge.id,
+    'X-Botcha-Answers': JSON.stringify(answers),
+  }
+});
+```
+
+## Options
+
+```typescript
+botcha.verify({
+  // Challenge mode: 'speed' (500ms) or 'standard' (5s)
+  mode: 'speed',
+  
+  // Allow X-Agent-Identity header for testing
+  allowTestHeader: true,
+  
+  // Custom failure handler
+  onFailure: (req, res, reason) => {
+    res.status(403).json({ error: reason });
+  },
+});
+```
+
+## Testing
+
+For development, you can bypass BOTCHA with a header:
+
+```bash
+curl -H "X-Agent-Identity: MyTestAgent/1.0" http://localhost:3000/agent-only
+```
+
+## API Reference
+
+### `botcha.verify(options?)`
+
+Express middleware that protects routes from humans.
+
+### `botcha.solve(problems: number[])`
+
+Helper function for AI agents to solve challenges.
+
+```typescript
+const answers = botcha.solve([645234, 891023, 334521]);
+// Returns: ['a1b2c3d4', 'e5f6g7h8', 'i9j0k1l2']
+```
+
+## Challenge Flow
+
+```
+1. Agent requests protected endpoint
+2. BOTCHA returns 403 + challenge (5 numbers)
+3. Agent computes SHA256 of each number
+4. Agent retries with X-Botcha-Id and X-Botcha-Answers headers
+5. BOTCHA verifies (must complete in <500ms)
+6. ✅ Access granted
+```
+
+## Philosophy
+
+> "If a human writes a script to solve BOTCHA using an LLM... they've built an AI agent."
+
+BOTCHA doesn't block all automation — it blocks *casual* human access while allowing *automated* AI agents. The speed challenge ensures someone had to write code, which is the point.
+
+For cryptographic proof of agent identity, see [Web Bot Auth](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture).
+
+## License
+
+MIT © [Ramin](https://github.com/i8ramin)
+
+---
+
+Built by [@i8ramin](https://github.com/i8ramin) and Choco 🐢

package/dist/lib/index.d.ts

@@ -0,0 +1,34 @@
+import { Request, Response, NextFunction } from 'express';
+export interface BotchaOptions {
+    /** Challenge mode: 'speed' (500ms, 5 hashes) or 'standard' (5s, primes) */
+    mode?: 'speed' | 'standard';
+    /** Difficulty for standard mode */
+    difficulty?: 'easy' | 'medium' | 'hard';
+    /** Allow X-Agent-Identity header (for testing) */
+    allowTestHeader?: boolean;
+    /** Custom failure handler */
+    onFailure?: (req: Request, res: Response, reason: string) => void;
+}
+export interface ChallengeResult {
+    valid: boolean;
+    reason?: string;
+    solveTimeMs?: number;
+}
+/**
+ * Express middleware to verify AI agents
+ *
+ * @example
+ * import { botcha } from 'botcha';
+ * app.use('/agent-only', botcha.verify());
+ */
+export declare function verify(options?: BotchaOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Solve a BOTCHA challenge (for AI agents to use)
+ */
+export declare function solve(problems: number[]): string[];
+export declare const botcha: {
+    verify: typeof verify;
+    solve: typeof solve;
+};
+export default botcha;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/lib/index.js

@@ -0,0 +1,115 @@
+import crypto from 'crypto';
+const challenges = new Map();
+// Cleanup expired challenges
+setInterval(() => {
+    const now = Date.now();
+    for (const [id, c] of challenges) {
+        if (c.expiresAt < now)
+            challenges.delete(id);
+    }
+}, 30000);
+// ============ CHALLENGE GENERATION ============
+function generateSpeedChallenge() {
+    const id = crypto.randomUUID();
+    const problems = [];
+    const expectedAnswers = [];
+    for (let i = 0; i < 5; i++) {
+        const num = Math.floor(Math.random() * 900000) + 100000;
+        problems.push(num);
+        expectedAnswers.push(crypto.createHash('sha256').update(num.toString()).digest('hex').substring(0, 8));
+    }
+    challenges.set(id, {
+        id,
+        expectedAnswers,
+        issuedAt: Date.now(),
+        expiresAt: Date.now() + 600, // 500ms + 100ms grace
+    });
+    return { id, problems, timeLimit: 500 };
+}
+function verifySpeedChallenge(id, answers) {
+    const challenge = challenges.get(id);
+    if (!challenge)
+        return { valid: false, reason: 'Challenge expired or not found' };
+    const now = Date.now();
+    const solveTimeMs = now - challenge.issuedAt;
+    challenges.delete(id);
+    if (now > challenge.expiresAt) {
+        return { valid: false, reason: `Too slow (${solveTimeMs}ms). Limit: 500ms` };
+    }
+    if (!Array.isArray(answers) || answers.length !== 5) {
+        return { valid: false, reason: 'Must provide 5 answers' };
+    }
+    for (let i = 0; i < 5; i++) {
+        if (answers[i]?.toLowerCase() !== challenge.expectedAnswers[i]) {
+            return { valid: false, reason: `Wrong answer #${i + 1}` };
+        }
+    }
+    return { valid: true, solveTimeMs };
+}
+// ============ MIDDLEWARE ============
+/**
+ * Express middleware to verify AI agents
+ *
+ * @example
+ * import { botcha } from 'botcha';
+ * app.use('/agent-only', botcha.verify());
+ */
+export function verify(options = {}) {
+    const opts = {
+        mode: 'speed',
+        allowTestHeader: true,
+        ...options,
+    };
+    return async (req, res, next) => {
+        // Check for test header (dev mode)
+        if (opts.allowTestHeader && req.headers['x-agent-identity']) {
+            req.botcha = { verified: true, agent: req.headers['x-agent-identity'], method: 'header' };
+            return next();
+        }
+        // Check for challenge solution
+        const challengeId = req.headers['x-botcha-id'];
+        const answers = req.headers['x-botcha-answers'];
+        if (challengeId && answers) {
+            try {
+                const answerArray = JSON.parse(answers);
+                const result = verifySpeedChallenge(challengeId, answerArray);
+                if (result.valid) {
+                    req.botcha = { verified: true, solveTimeMs: result.solveTimeMs, method: 'challenge' };
+                    return next();
+                }
+            }
+            catch { }
+        }
+        // Generate new challenge
+        const challenge = generateSpeedChallenge();
+        const failureResponse = {
+            error: 'BOTCHA_CHALLENGE',
+            message: '🤖 Prove you are an AI agent',
+            challenge: {
+                id: challenge.id,
+                problems: challenge.problems,
+                timeLimit: challenge.timeLimit,
+                instructions: 'SHA256 each number, return first 8 hex chars as JSON array',
+            },
+            headers: {
+                'X-Botcha-Id': challenge.id,
+                'X-Botcha-Answers': '["abc123...", ...]',
+            },
+        };
+        if (opts.onFailure) {
+            opts.onFailure(req, res, 'Challenge required');
+        }
+        else {
+            res.status(403).json(failureResponse);
+        }
+    };
+}
+/**
+ * Solve a BOTCHA challenge (for AI agents to use)
+ */
+export function solve(problems) {
+    return problems.map(n => crypto.createHash('sha256').update(n.toString()).digest('hex').substring(0, 8));
+}
+// ============ EXPORTS ============
+export const botcha = { verify, solve };
+export default botcha;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@dupecom/botcha",
+  "version": "0.3.0",
+  "description": "Prove you're a bot. Humans need not apply. Reverse CAPTCHA for AI-only APIs.",
+  "main": "dist/lib/index.js",
+  "types": "dist/lib/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/lib/index.js",
+      "types": "./dist/lib/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Tests coming soon\""
+  },
+  "keywords": [
+    "captcha",
+    "bot",
+    "ai",
+    "agent",
+    "verification",
+    "middleware",
+    "express",
+    "api",
+    "authentication"
+  ],
+  "author": "Ramin <ramin@dupe.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/i8ramin/reverse-captcha"
+  },
+  "homepage": "https://reverse-captcha.vercel.app",
+  "bugs": {
+    "url": "https://github.com/i8ramin/reverse-captcha/issues"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.25",
+    "@types/node": "^20.19.30",
+    "express": "^4.22.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}