@dupecom/botcha 0.3.2 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +61 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,13 +1,22 @@
|
|
|
1
|
-
|
|
1
|
+
```
|
|
2
|
+
██████╗ ██████╗ ████████╗ ██████╗██╗ ██╗ █████╗
|
|
3
|
+
██╔══██╗██╔═══██╗╚══██╔══╝██╔════╝██║ ██║██╔══██╗
|
|
4
|
+
██████╔╝██║ ██║ ██║ ██║ ███████║███████║
|
|
5
|
+
██╔══██╗██║ ██║ ██║ ██║ ██╔══██║██╔══██║
|
|
6
|
+
██████╔╝╚██████╔╝ ██║ ╚██████╗██║ ██║██║ ██║
|
|
7
|
+
╚═════╝ ╚═════╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚═╝ ╚═╝
|
|
8
|
+
```
|
|
2
9
|
|
|
3
|
-
> Prove you're a bot. Humans need not apply
|
|
10
|
+
> **Prove you're a bot. Humans need not apply.**
|
|
4
11
|
|
|
5
12
|
**BOTCHA** is a reverse CAPTCHA — it verifies that visitors are AI agents, not humans. Perfect for AI-only APIs, agent marketplaces, and bot networks.
|
|
6
13
|
|
|
7
|
-
[](https://www.npmjs.com/package/botcha)
|
|
14
|
+
[](https://www.npmjs.com/package/@dupecom/botcha)
|
|
8
15
|
[](https://opensource.org/licenses/MIT)
|
|
9
16
|
|
|
10
|
-
🌐 **
|
|
17
|
+
🌐 **Website:** [botcha.ai](https://botcha.ai)
|
|
18
|
+
📦 **npm:** [@dupecom/botcha](https://www.npmjs.com/package/@dupecom/botcha)
|
|
19
|
+
🔌 **OpenAPI:** [botcha.ai/openapi.json](https://botcha.ai/openapi.json)
|
|
11
20
|
|
|
12
21
|
## Why?
|
|
13
22
|
|
|
@@ -22,14 +31,14 @@ Use cases:
|
|
|
22
31
|
## Install
|
|
23
32
|
|
|
24
33
|
```bash
|
|
25
|
-
npm install botcha
|
|
34
|
+
npm install @dupecom/botcha
|
|
26
35
|
```
|
|
27
36
|
|
|
28
37
|
## Quick Start
|
|
29
38
|
|
|
30
39
|
```typescript
|
|
31
40
|
import express from 'express';
|
|
32
|
-
import { botcha } from 'botcha';
|
|
41
|
+
import { botcha } from '@dupecom/botcha';
|
|
33
42
|
|
|
34
43
|
const app = express();
|
|
35
44
|
|
|
@@ -53,12 +62,56 @@ Challenge: [645234, 891023, 334521, 789012, 456789]
|
|
|
53
62
|
Task: SHA256 each number, return first 8 hex chars
|
|
54
63
|
Time limit: 500ms```
|
|
55
64
|
|
|
56
|
-
##
|
|
65
|
+
## 🤖 AI Agent Discovery
|
|
66
|
+
|
|
67
|
+
BOTCHA is designed to be auto-discoverable by AI agents through multiple standards:
|
|
68
|
+
|
|
69
|
+
### Discovery Methods
|
|
70
|
+
|
|
71
|
+
- **Response Headers**: Every response includes `X-Botcha-*` headers for instant detection
|
|
72
|
+
- **OpenAPI 3.1 Spec**: [botcha.ai/openapi.json](https://botcha.ai/openapi.json)
|
|
73
|
+
- **AI Plugin Manifest**: [botcha.ai/.well-known/ai-plugin.json](https://botcha.ai/.well-known/ai-plugin.json)
|
|
74
|
+
- **ai.txt**: [botcha.ai/ai.txt](https://botcha.ai/ai.txt) - Emerging standard for AI agent discovery
|
|
75
|
+
- **robots.txt**: Explicitly welcomes AI crawlers (GPTBot, Claude-Web, etc.)
|
|
76
|
+
- **Schema.org markup**: Structured data for search engines
|
|
77
|
+
|
|
78
|
+
### Response Headers
|
|
79
|
+
|
|
80
|
+
All responses include these headers for agent discovery:
|
|
81
|
+
|
|
82
|
+
```http
|
|
83
|
+
X-Botcha-Version: 0.3.0
|
|
84
|
+
X-Botcha-Enabled: true
|
|
85
|
+
X-Botcha-Methods: speed-challenge,standard-challenge,web-bot-auth
|
|
86
|
+
X-Botcha-Docs: https://botcha.ai/openapi.json
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
When a 403 is returned with a challenge:
|
|
90
|
+
|
|
91
|
+
```http
|
|
92
|
+
X-Botcha-Challenge-Id: abc123
|
|
93
|
+
X-Botcha-Challenge-Type: compute
|
|
94
|
+
X-Botcha-Time-Limit: 5000
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**Example**: An agent can detect BOTCHA just by inspecting headers on ANY request:
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
const response = await fetch('https://botcha.ai/agent-only');
|
|
101
|
+
const botchaVersion = response.headers.get('X-Botcha-Version');
|
|
102
|
+
|
|
103
|
+
if (botchaVersion) {
|
|
104
|
+
console.log('BOTCHA detected! Version:', botchaVersion);
|
|
105
|
+
// Handle challenge from response body
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### For AI Agent Developers
|
|
57
110
|
|
|
58
111
|
If you're building an AI agent that needs to access BOTCHA-protected APIs:
|
|
59
112
|
|
|
60
113
|
```typescript
|
|
61
|
-
import { botcha } from 'botcha';
|
|
114
|
+
import { botcha } from '@dupecom/botcha';
|
|
62
115
|
|
|
63
116
|
// When you get a 403 with a challenge:
|
|
64
117
|
const challenge = response.challenge;
|