@dupecom/botcha 0.10.0 → 0.13.0

package/README.md

@@ -35,6 +35,8 @@ Use cases:
 - 📊 Per-app metrics dashboard at [botcha.ai/dashboard](https://botcha.ai/dashboard)
 - 📧 Email verification, account recovery, and secret rotation
 - 🤖 Agent-first dashboard auth (challenge-based login + device code handoff)
+- 🆔 Persistent agent identities with registry
+- 🔏 Trusted Agent Protocol (TAP) — cryptographic agent auth with HTTP Message Signatures
 
 ## Install
 
@@ -121,10 +123,11 @@ BOTCHA uses **OAuth2-style token rotation** with short-lived access tokens and l
 ### Token Flow
 
 ```
-1. Solve challenge → receive access_token (5min) + refresh_token (1hr)
+1. Solve challenge → receive access_token (5min) + refresh_token (1hr) + human_link
 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
+3. Give human_link to your human → they click it → instant browser access via /go/:code
+4. When access_token expires → POST /v1/token/refresh with refresh_token
+5. When compromised → POST /v1/token/revoke to invalidate immediately
 ```
 
 ### Security Features
@@ -159,7 +162,7 @@ async with BotchaClient(audience="https://api.example.com") as client:
 | Endpoint | Description |
 |----------|-------------|
 | `GET /v1/token` | Get challenge for token flow |
-| `POST /v1/token/verify` | Submit solution → receive `access_token` + `refresh_token` |
+| `POST /v1/token/verify` | Submit solution → receive `access_token` + `refresh_token` + `human_link` |
 | `POST /v1/token/refresh` | Exchange `refresh_token` for new `access_token` |
 | `POST /v1/token/revoke` | Invalidate any token immediately |
 
@@ -237,6 +240,32 @@ async with BotchaClient(app_id="app_abc123") as client:
     response = await client.fetch("https://api.example.com/agent-only")
 ```
 
+### SDK App Lifecycle (v0.10.0+)
+
+Both SDKs now include methods for the full app lifecycle:
+
+**TypeScript:**
+
+```typescript
+const client = new BotchaClient();
+const app = await client.createApp('agent@example.com'); // auto-sets appId
+await client.verifyEmail('123456');                       // verify with email code
+await client.resendVerification();                        // resend code
+await client.recoverAccount('agent@example.com');         // recovery device code via email
+const rotated = await client.rotateSecret();              // rotate secret (auth required)
+```
+
+**Python:**
+
+```python
+async with BotchaClient() as client:
+    app = await client.create_app("agent@example.com")  # auto-sets app_id
+    await client.verify_email("123456")                  # verify with email code
+    await client.resend_verification()                   # resend code
+    await client.recover_account("agent@example.com")    # recovery device code via email
+    rotated = await client.rotate_secret()               # rotate secret (auth required)
+```
+
 ### Rate Limiting
 
 Each app gets its own rate limit bucket:
@@ -285,6 +314,125 @@ Session uses cookie-based auth (HttpOnly, Secure, SameSite=Lax, 1hr expiry).
 
 All metrics support `1h`, `24h`, `7d`, and `30d` time windows via htmx-powered buttons — no page reload required.
 
+## 🤖 Agent Registry
+
+BOTCHA now supports **persistent agent identities** — register your agent with a name, operator, and version to build a verifiable identity over time.
+
+### Why Register an Agent?
+
+- **Identity**: Get a persistent `agent_id` that survives across sessions
+- **Attribution**: Track which agent made which API calls
+- **Reputation**: Build trust over time (foundation for future reputation scoring)
+- **Accountability**: Know who's operating each agent
+
+### Registering an Agent
+
+```bash
+# Register a new agent (requires app_id)
+curl -X POST "https://botcha.ai/v1/agents/register?app_id=app_abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-assistant",
+    "operator": "Acme Corp",
+    "version": "1.0.0"
+  }'
+
+# Returns:
+{
+  "agent_id": "agent_xyz789",
+  "app_id": "app_abc123",
+  "name": "my-assistant",
+  "operator": "Acme Corp",
+  "version": "1.0.0",
+  "created_at": 1770936000000
+}
+```
+
+### Agent Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /v1/agents/register` | Create a new agent identity (requires `app_id`) |
+| `GET /v1/agents/:id` | Get agent info by ID (public, no auth) |
+| `GET /v1/agents` | List all agents for authenticated app |
+
+> **Note:** Agent Registry is the foundation for future features like delegation chains, capability attestation, and reputation scoring. See [ROADMAP.md](./ROADMAP.md) for details.
+
+## 🔏 Trusted Agent Protocol (TAP)
+
+BOTCHA v0.12.0 introduces the **Trusted Agent Protocol** — enterprise-grade cryptographic agent authentication using HTTP Message Signatures (RFC 9421).
+
+### Why TAP?
+
+- **Cryptographic Identity**: Agents register public keys and sign requests — no more shared secrets
+- **Capability Scoping**: Define exactly what an agent can do (`read:invoices`, `write:transfers`)
+- **Intent Verification**: Every session requires a declared intent that's validated against capabilities
+- **Trust Levels**: `basic`, `verified`, `enterprise` — different access tiers for different agents
+
+### Registering a TAP Agent
+
+```bash
+# Register with public key and capabilities
+curl -X POST "https://botcha.ai/v1/agents/register/tap?app_id=app_abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "enterprise-agent",
+    "operator": "Acme Corp",
+    "version": "2.0.0",
+    "public_key": "-----BEGIN PUBLIC KEY-----\nMFkw...\n-----END PUBLIC KEY-----",
+    "signature_algorithm": "ecdsa-p256-sha256",
+    "trust_level": "enterprise",
+    "capabilities": [
+      {"action": "read", "resource": "/api/invoices"},
+      {"action": "write", "resource": "/api/orders", "constraints": {"max_amount": 10000}}
+    ]
+  }'
+```
+
+### Creating a TAP Session
+
+```bash
+# Create session with intent declaration
+curl -X POST https://botcha.ai/v1/sessions/tap \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent_id": "agent_xyz789",
+    "user_context": "user_123",
+    "intent": {
+      "action": "read",
+      "resource": "/api/invoices",
+      "purpose": "Monthly billing report"
+    }
+  }'
+```
+
+### TAP Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /v1/agents/register/tap` | Register TAP agent with public key + capabilities |
+| `GET /v1/agents/:id/tap` | Get TAP agent details (includes public key) |
+| `GET /v1/agents/tap` | List TAP-enabled agents for app |
+| `POST /v1/sessions/tap` | Create TAP session with intent validation |
+| `GET /v1/sessions/:id/tap` | Get TAP session info |
+
+### Express Middleware (Verification Modes)
+
+```typescript
+import { createTAPVerifyMiddleware } from '@dupecom/botcha/middleware';
+
+// Mode: 'tap' — require TAP signature
+app.use('/api', createTAPVerifyMiddleware({ mode: 'tap', secret: process.env.BOTCHA_SECRET }));
+
+// Mode: 'flexible' — accept TAP signature OR challenge token
+app.use('/api', createTAPVerifyMiddleware({ mode: 'flexible', secret: process.env.BOTCHA_SECRET }));
+
+// Mode: 'challenge-only' — traditional BOTCHA challenge (backward compatible)
+app.use('/api', createTAPVerifyMiddleware({ mode: 'challenge-only', secret: process.env.BOTCHA_SECRET }));
+```
+
+> **Supported algorithms:** `ecdsa-p256-sha256`, `rsa-pss-sha256`. See [ROADMAP.md](./ROADMAP.md) for details.
+
 ## 🔄 SSE Streaming Flow (AI-Native)
 
 For AI agents that prefer a **conversational handshake**, BOTCHA offers **Server-Sent Events (SSE)** streaming:
@@ -362,7 +510,7 @@ 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.5.0
+X-Botcha-Version: 0.12.0
 X-Botcha-Enabled: true
 X-Botcha-Methods: hybrid-challenge,speed-challenge,reasoning-challenge,standard-challenge
 X-Botcha-Docs: https://botcha.ai/openapi.json

package/dist/lib/client/index.js

@@ -1,6 +1,6 @@
 import crypto from 'crypto';
 // SDK version - hardcoded since npm_package_version is unreliable when used as a library
-const SDK_VERSION = '0.10.0';
+const SDK_VERSION = '0.11.0';
 // Export stream client
 export { BotchaStreamClient } from './stream.js';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dupecom/botcha",
-  "version": "0.10.0",
+  "version": "0.13.0",
   "description": "Prove you're a bot. Humans need not apply. Reverse CAPTCHA for AI-only APIs.",
   "workspaces": [
     "packages/*"