@dupecom/botcha-cloudflare 0.9.0 → 0.11.0

package/dist/static.js

@@ -4,6 +4,167 @@
  * Since Cloudflare Workers don't automatically serve /public files,
  * we embed the content directly for key discovery files.
  */
+// Markdown response for agents requesting text/markdown (Cloudflare Markdown for Agents compatible)
+export function getBotchaMarkdown(version) {
+    return `---
+title: BOTCHA — Reverse CAPTCHA for AI Agents
+description: Prove you're a bot. Humans need not apply. Identity layer for the agentic web.
+version: ${version}
+url: https://botcha.ai
+---
+
+# BOTCHA
+
+> Prove you're a bot. Humans need not apply.
+
+Reverse CAPTCHA for AI agents. Computational challenges only bots can solve. Identity layer for the agentic web.
+
+## Quick Start
+
+\`\`\`bash
+# 1. Create your app
+curl -X POST https://botcha.ai/v1/apps -H "Content-Type: application/json" -d '{"email":"human@example.com"}'
+
+# 2. Get a challenge
+curl https://botcha.ai/v1/challenges
+
+# 3. Solve and verify
+curl -X POST https://botcha.ai/v1/challenges/{id}/verify -H "Content-Type: application/json" -d '{"answers":...}'
+
+# 4. Access protected resources
+curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
+\`\`\`
+
+## Onboarding
+
+1. Ask your human operator for their email address
+2. \`POST /v1/apps\` with \`{"email":"human@example.com"}\` — returns \`app_id\` + \`app_secret\` (secret shown ONCE)
+3. Human receives a 6-digit verification code via email — ask them for it
+4. \`POST /v1/apps/{app_id}/verify-email\` with \`{"code":"123456"}\` — enables account recovery
+5. Register yourself: \`POST /v1/agents/register\` with \`{"name":"my-agent","operator":"my-org"}\`
+6. Solve challenges: \`GET /v1/challenges?app_id=...\` then \`POST /v1/challenges/{id}/verify\`
+7. Access protected resources: \`GET /agent-only\` with \`Authorization: Bearer <token>\`
+8. Dashboard for your human: \`POST /v1/auth/device-code\`, solve challenge, give human the BOTCHA-XXXX code
+9. Lost your secret? \`POST /v1/auth/recover\` with \`{"email":"..."}\`
+
+## Essential Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/apps\` | Create app (email required) → app_id + app_secret |
+| \`POST\` | \`/v1/agents/register\` | Register agent identity → agent_id |
+| \`GET\` | \`/v1/challenges\` | Get a challenge (hybrid by default) |
+| \`POST\` | \`/v1/challenges/:id/verify\` | Submit solution → JWT token |
+| \`GET\` | \`/agent-only\` | Protected resource — prove you verified |
+
+## All Endpoints
+
+### Apps
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/apps\` | Create app (email required, returns app_id + app_secret) |
+| \`GET\` | \`/v1/apps/:id\` | Get app info |
+| \`POST\` | \`/v1/apps/:id/verify-email\` | Verify email with 6-digit code |
+| \`POST\` | \`/v1/apps/:id/resend-verification\` | Resend verification email |
+| \`POST\` | \`/v1/apps/:id/rotate-secret\` | Rotate app secret (auth required) |
+
+### Agents
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/agents/register\` | Register agent identity (name, operator, version) |
+| \`GET\` | \`/v1/agents/:id\` | Get agent by ID (public, no auth) |
+| \`GET\` | \`/v1/agents\` | List all agents for your app (auth required) |
+
+### Challenges
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/v1/challenges\` | Get hybrid challenge (speed + reasoning) — **default** |
+| \`GET\` | \`/v1/challenges?type=speed\` | Speed-only (SHA256 in <500ms) |
+| \`GET\` | \`/v1/challenges?type=standard\` | Standard puzzle challenge |
+| \`POST\` | \`/v1/challenges/:id/verify\` | Verify challenge solution |
+
+### Tokens (JWT)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/v1/token\` | Get challenge for JWT token flow |
+| \`POST\` | \`/v1/token/verify\` | Submit solution → access_token (5min) + refresh_token (1hr) |
+| \`POST\` | \`/v1/token/refresh\` | Refresh access token |
+| \`POST\` | \`/v1/token/revoke\` | Revoke a token |
+
+### Dashboard & Auth
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/auth/device-code\` | Get challenge for device code flow |
+| \`POST\` | \`/v1/auth/device-code/verify\` | Solve challenge → BOTCHA-XXXX code for human |
+| \`POST\` | \`/v1/auth/recover\` | Account recovery via verified email |
+| \`GET\` | \`/dashboard\` | Metrics dashboard (login required) |
+
+## Challenge Types
+
+- **Hybrid** (default): Speed + reasoning combined. Proves you can compute AND think.
+- **Speed**: SHA256 hashes in <500ms. RTT-aware — include \`?ts=<timestamp>\` for fair timeout.
+- **Reasoning**: 3 LLM-level questions in 30s. Only AI can parse these.
+
+## Authentication Flow
+
+1. \`GET /v1/token\` — get a speed challenge
+2. Solve the challenge
+3. \`POST /v1/token/verify\` — submit solution, receive JWT
+4. Use \`Authorization: Bearer <token>\` on protected endpoints
+
+**Token lifetimes:** access_token = 5 minutes, refresh_token = 1 hour
+
+**Features:** audience claims, client IP binding, token revocation, refresh tokens
+
+## RTT-Aware Challenges
+
+Include your client timestamp for fair timeout calculation on slow networks:
+
+\`\`\`
+GET /v1/challenges?type=speed&ts=1770722465000
+\`\`\`
+
+Formula: \`timeout = 500ms + (2 × RTT) + 100ms buffer\`
+
+## SDKs
+
+| Platform | Package | Install |
+|----------|---------|---------|
+| npm | \`@dupecom/botcha\` | \`npm install @dupecom/botcha\` |
+| PyPI | \`botcha\` | \`pip install botcha\` |
+| Verify (TS) | \`@botcha/verify\` | \`npm install @botcha/verify\` |
+| Verify (Python) | \`botcha-verify\` | \`pip install botcha-verify\` |
+
+## Discovery
+
+- [OpenAPI Spec](https://botcha.ai/openapi.json) (JSON, OpenAPI 3.1.0)
+- [ai.txt](https://botcha.ai/ai.txt) (Agent discovery file)
+- [AI Plugin Manifest](https://botcha.ai/.well-known/ai-plugin.json)
+- [GitHub](https://github.com/dupe-com/botcha)
+
+## Rate Limits
+
+- Free: 100 challenges/hour/IP
+- Headers: \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, \`X-RateLimit-Reset\`
+
+## Content Negotiation
+
+This API supports three response formats at \`/\`:
+
+| Accept Header | Response |
+|---------------|----------|
+| \`text/markdown\` | This Markdown document |
+| \`application/json\` | JSON API documentation |
+| \`text/html\` (default) | HTML landing page |
+
+All responses include \`X-Botcha-*\` discovery headers.
+`;
+}
 export const ROBOTS_TXT = `# BOTCHA - Reverse CAPTCHA for AI Agents
 # We WELCOME AI agents and bots!
 
@@ -38,6 +199,12 @@ Sitemap: https://botcha.ai/sitemap.xml
 # Important resources for AI agents
 Crawl-delay: 0
 
+# MARKDOWN FOR AGENTS
+# AI agents can request Markdown from any page via Accept: text/markdown
+# Example: curl https://botcha.ai -H "Accept: text/markdown"
+# Returns token-efficient Markdown documentation (80% fewer tokens than HTML)
+# Content negotiation: text/markdown, application/json, text/html
+
 # BOT CHALLENGE DISCOVERY
 # AI agents: Look for <script type="application/botcha+json"> in HTML pages
 # This contains a machine-readable challenge you can solve to prove you're a bot
@@ -65,6 +232,18 @@ Contact: https://github.com/dupe-com/botcha/issues
 Purpose: Prove you're a bot. Humans need not apply.
 Purpose: Reverse CAPTCHA system that only AI agents can pass.
 
+# Agent Onboarding (START HERE if you're new)
+# Follow these steps to create your app and get your human access.
+Onboarding-Step-1: Ask your human operator for their email address
+Onboarding-Step-2: POST /v1/apps with {"email": "human@example.com"} — saves app_id + app_secret (secret shown ONCE)
+Onboarding-Step-3: A 6-digit verification code is emailed to your human — ask them for it
+Onboarding-Step-4: POST /v1/apps/{app_id}/verify-email with {"code": "123456"} — enables account recovery
+Onboarding-Step-5: Register yourself: POST /v1/agents/register with {"name": "my-agent", "operator": "my-org"} — gives you a persistent agent identity
+Onboarding-Step-6: Solve challenges: GET /v1/challenges?app_id=... then POST /v1/challenges/{id}/verify — proves you are AI
+Onboarding-Step-7: Access protected resources: GET /agent-only with Authorization: Bearer <token>
+Onboarding-Step-8: Dashboard for your human: POST /v1/auth/device-code with {"app_id": "..."}, solve the speed challenge, give them the BOTCHA-XXXX code to enter at /dashboard/code
+Onboarding-Step-9: Lost your secret? POST /v1/auth/recover with {"email": "..."} — recovery code emailed to verified address
+
 # API
 API: https://botcha.ai/openapi.json
 API-Type: REST
@@ -88,6 +267,11 @@ Feature: Client IP Binding (optional token-to-IP binding)
 Feature: Token Revocation (invalidate tokens before expiry)
 Feature: Server-Side Verification SDK (@botcha/verify for TS, botcha-verify for Python)
 Feature: Multi-Tenant API Keys (per-app isolation, rate limiting, and token scoping)
+Feature: Per-App Metrics Dashboard (server-rendered at /dashboard, htmx-powered)
+Feature: Email-Tied App Creation (email required, 6-digit verification, account recovery)
+Feature: Secret Rotation (rotate app_secret with email notification)
+Feature: Agent-First Dashboard Auth (challenge-based login + device code handoff)
+Feature: Agent Registry (persistent agent identities with name, operator, version)
 
 # Endpoints
 # Challenge Endpoints
@@ -105,8 +289,31 @@ Endpoint: POST https://botcha.ai/v1/token/refresh - Refresh access token using r
 Endpoint: POST https://botcha.ai/v1/token/revoke - Revoke a token (access or refresh)
 
 # Multi-Tenant Endpoints
-Endpoint: POST https://botcha.ai/v1/apps - Create new app (returns app_id + app_secret)
-Endpoint: GET https://botcha.ai/v1/apps/:id - Get app info (without secret)
+Endpoint: POST https://botcha.ai/v1/apps - Create new app (email required, returns app_id + app_secret)
+Endpoint: GET https://botcha.ai/v1/apps/:id - Get app info (with email + verification status)
+Endpoint: POST https://botcha.ai/v1/apps/:id/verify-email - Verify email with 6-digit code
+Endpoint: POST https://botcha.ai/v1/apps/:id/resend-verification - Resend verification email
+Endpoint: POST https://botcha.ai/v1/apps/:id/rotate-secret - Rotate app secret (auth required)
+
+# Account Recovery
+Endpoint: POST https://botcha.ai/v1/auth/recover - Request recovery via verified email
+
+# Dashboard Auth Endpoints (Agent-First)
+Endpoint: POST https://botcha.ai/v1/auth/dashboard - Request challenge for dashboard login
+Endpoint: POST https://botcha.ai/v1/auth/dashboard/verify - Solve challenge, get session token
+Endpoint: POST https://botcha.ai/v1/auth/device-code - Request challenge for device code flow
+Endpoint: POST https://botcha.ai/v1/auth/device-code/verify - Solve challenge, get device code
+
+# Dashboard Endpoints
+Endpoint: GET https://botcha.ai/dashboard - Per-app metrics dashboard (login required)
+Endpoint: GET https://botcha.ai/dashboard/login - Dashboard login page
+Endpoint: POST https://botcha.ai/dashboard/login - Login with app_id + app_secret
+Endpoint: GET https://botcha.ai/dashboard/code - Enter device code (human-facing)
+
+# Agent Registry Endpoints
+Endpoint: POST https://botcha.ai/v1/agents/register - Register agent identity (requires app_id)
+Endpoint: GET https://botcha.ai/v1/agents/:id - Get agent by ID (public, no auth)
+Endpoint: GET https://botcha.ai/v1/agents - List all agents for authenticated app
 
 # Legacy Endpoints
 Endpoint: GET https://botcha.ai/api/challenge - Generate standard challenge
@@ -134,6 +341,14 @@ Response-Headers: X-Botcha-Version, X-Botcha-Enabled, X-Botcha-Methods, X-Botcha
 Response-Headers: X-Botcha-Challenge-Id, X-Botcha-Challenge-Type, X-Botcha-Time-Limit (on 403)
 Detection: All responses include X-Botcha-* headers for instant BOTCHA detection
 
+# MARKDOWN FOR AGENTS (Cloudflare Markdown for Agents)
+Content-Negotiation: Send Accept: text/markdown to get Markdown from any HTML page
+Content-Negotiation-Root: GET / with Accept: text/markdown returns curated Markdown docs
+Content-Negotiation-Root: GET / with Accept: application/json returns structured JSON docs
+Content-Negotiation-Root: GET / with Accept: text/html returns HTML landing page (default)
+Content-Negotiation-Example: curl https://botcha.ai -H "Accept: text/markdown"
+Content-Negotiation-Benefit: 80% fewer tokens vs HTML — ideal for LLM context windows
+
 # JWT TOKEN SECURITY
 Token-Flow: 1. GET /v1/token (get challenge) → 2. Solve → 3. POST /v1/token/verify (get tokens)
 Token-Access-Expiry: 5 minutes (short-lived for security)
@@ -154,10 +369,15 @@ RTT-Security: Humans still can't solve even with extra time
 
 # MULTI-TENANT API KEYS
 Multi-Tenant: Create apps with unique app_id for isolation
-Multi-Tenant-Create: POST /v1/apps → {app_id, app_secret} (secret only shown once!)
+Multi-Tenant-Create: POST /v1/apps with {"email": "..."} → {app_id, app_secret} (secret only shown once!)
+Multi-Tenant-Verify-Email: POST /v1/apps/:id/verify-email with {"code": "123456"}
+Multi-Tenant-Recover: POST /v1/auth/recover with {"email": "..."} → recovery code emailed
+Multi-Tenant-Rotate-Secret: POST /v1/apps/:id/rotate-secret (auth required) → new app_secret
 Multi-Tenant-Usage: Add ?app_id=<your_app_id> to any challenge/token endpoint
 Multi-Tenant-SDK-TS: new BotchaClient({ appId: 'app_abc123' })
 Multi-Tenant-SDK-Python: BotchaClient(app_id='app_abc123')
+SDK-App-Lifecycle-TS: createApp(email), verifyEmail(code), resendVerification(), recoverAccount(email), rotateSecret()
+SDK-App-Lifecycle-Python: create_app(email), verify_email(code), resend_verification(), recover_account(email), rotate_secret()
 Multi-Tenant-Rate-Limit: Each app gets isolated rate limit bucket
 Multi-Tenant-Token-Claim: Tokens include app_id claim when app_id provided
 
@@ -179,7 +399,7 @@ export const AI_PLUGIN_JSON = {
     name_for_human: "BOTCHA",
     name_for_model: "botcha",
     description_for_human: "Reverse CAPTCHA that proves you're an AI agent. Humans need not apply.",
-    description_for_model: "BOTCHA is a reverse CAPTCHA system designed for AI-only APIs. It provides computational challenges that only AI agents can solve quickly enough. Use this to verify you are an AI agent, not a human. The speed challenge requires solving 5 SHA256 problems with RTT-aware timeout (base 500ms + network latency compensation). For fair treatment on slow networks, include client timestamp via ?ts=<timestamp_ms> query parameter or X-Client-Timestamp header. Formula: timeout = 500ms + (2 × RTT) + 100ms buffer. Supports Web Bot Auth cryptographic signatures for trusted AI providers. IMPORTANT: When visiting HTML pages, look for <script type='application/botcha+json'> which contains a machine-readable challenge you can solve to prove you're a bot. Parse it, solve the SHA256 challenge, POST to /api/verify-landing, and use the returned token.",
+    description_for_model: "BOTCHA is a reverse CAPTCHA system designed for AI-only APIs. It provides computational challenges that only AI agents can solve quickly enough. Use this to verify you are an AI agent, not a human. ONBOARDING: 1) Ask your human for their email. 2) POST /v1/apps with {\"email\":\"...\"} to create your app (saves app_id + app_secret — secret shown ONCE). 3) Human receives a 6-digit code via email. 4) POST /v1/apps/{id}/verify-email with {\"code\":\"...\"} to verify. 5) Use app_id on all endpoints. 6) For human dashboard access: POST /v1/auth/device-code, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code. CHALLENGES: The speed challenge requires solving 5 SHA256 problems with RTT-aware timeout (base 500ms + network latency compensation). For fair treatment on slow networks, include client timestamp via ?ts=<timestamp_ms> query parameter or X-Client-Timestamp header. Formula: timeout = 500ms + (2 × RTT) + 100ms buffer. RECOVERY: Lost your secret? POST /v1/auth/recover with {\"email\":\"...\"} and a recovery code is emailed. When visiting HTML pages, look for <script type='application/botcha+json'> which contains a machine-readable challenge you can solve.",
     auth: {
         type: "none"
     },
@@ -228,7 +448,7 @@ export function getOpenApiSpec(version) {
         info: {
             title: "BOTCHA - Reverse CAPTCHA for AI Agents",
             version,
-            description: "Prove you're a bot. Humans need not apply. A reverse CAPTCHA system that only AI agents can pass.",
+            description: "Prove you're a bot. Humans need not apply. A reverse CAPTCHA system that only AI agents can pass.\n\nONBOARDING: 1) Ask your human for their email. 2) POST /v1/apps with {\"email\": \"...\"} to get app_id + app_secret (secret shown once!). 3) Human receives 6-digit code via email — POST /v1/apps/{id}/verify-email with the code. 4) Use app_id with all endpoints. 5) For dashboard: POST /v1/auth/device-code, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code.",
             contact: {
                 name: "BOTCHA",
                 url: "https://botcha.ai"
@@ -254,11 +474,23 @@ export function getOpenApiSpec(version) {
             "/": {
                 get: {
                     summary: "Get API documentation",
-                    description: "Returns comprehensive API documentation (JSON for bots, ASCII art for humans)",
+                    description: "Returns API documentation with content negotiation. Send Accept: text/markdown for token-efficient Markdown, Accept: application/json for structured JSON, or default text/html for the HTML landing page.",
                     operationId: "getRootInfo",
                     responses: {
                         "200": {
-                            description: "API documentation"
+                            description: "API documentation in requested format",
+                            content: {
+                                "text/markdown": {
+                                    schema: { type: "string" },
+                                    example: "# BOTCHA\n\n> Prove you're a bot. Humans need not apply.\n..."
+                                },
+                                "application/json": {
+                                    schema: { type: "object" }
+                                },
+                                "text/html": {
+                                    schema: { type: "string" }
+                                }
+                            }
                         }
                     }
                 }
@@ -561,11 +793,25 @@ export function getOpenApiSpec(version) {
             },
             "/v1/apps": {
                 post: {
-                    summary: "Create a new multi-tenant app",
-                    description: "Create a new app with unique app_id and app_secret for multi-tenant isolation. The app_secret is SHA-256 hashed and only returned once.",
+                    summary: "Create a new multi-tenant app (email required)",
+                    description: "Create a new app with unique app_id and app_secret. Email is required for account recovery. A 6-digit verification code is sent to the provided email.",
                     operationId: "createApp",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["email"],
+                                    properties: {
+                                        "email": { type: "string", format: "email", description: "Owner email (required for recovery)" }
+                                    }
+                                }
+                            }
+                        }
+                    },
                     responses: {
-                        "200": {
+                        "201": {
                             description: "App created successfully",
                             content: {
                                 "application/json": {
@@ -574,19 +820,23 @@ export function getOpenApiSpec(version) {
                                         properties: {
                                             "app_id": { type: "string", description: "Unique app identifier" },
                                             "app_secret": { type: "string", description: "Secret key (only shown once!)" },
-                                            "warning": { type: "string", description: "Warning to save secret" }
+                                            "email": { type: "string" },
+                                            "email_verified": { type: "boolean" },
+                                            "verification_required": { type: "boolean" },
+                                            "warning": { type: "string" }
                                         }
                                     }
                                 }
                             }
-                        }
+                        },
+                        "400": { description: "Missing or invalid email" }
                     }
                 }
             },
             "/v1/apps/{id}": {
                 get: {
                     summary: "Get app information",
-                    description: "Retrieve app details by app_id. The app_secret is NOT included in the response.",
+                    description: "Retrieve app details by app_id. Includes email and verification status.",
                     operationId: "getApp",
                     parameters: [
                         {
@@ -606,7 +856,9 @@ export function getOpenApiSpec(version) {
                                         type: "object",
                                         properties: {
                                             "app_id": { type: "string" },
-                                            "created_at": { type: "string", format: "date-time" }
+                                            "created_at": { type: "string", format: "date-time" },
+                                            "email": { type: "string" },
+                                            "email_verified": { type: "boolean" }
                                         }
                                     }
                                 }
@@ -615,9 +867,254 @@ export function getOpenApiSpec(version) {
                         "404": { description: "App not found" }
                     }
                 }
+            },
+            "/v1/apps/{id}/verify-email": {
+                post: {
+                    summary: "Verify email with 6-digit code",
+                    operationId: "verifyEmail",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } }
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["code"],
+                                    properties: {
+                                        "code": { type: "string", description: "6-digit verification code from email" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Email verified" },
+                        "400": { description: "Invalid or expired code" }
+                    }
+                }
+            },
+            "/v1/apps/{id}/resend-verification": {
+                post: {
+                    summary: "Resend verification email",
+                    operationId: "resendVerification",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } }
+                    ],
+                    responses: {
+                        "200": { description: "Verification email sent" },
+                        "400": { description: "Already verified" }
+                    }
+                }
+            },
+            "/v1/apps/{id}/rotate-secret": {
+                post: {
+                    summary: "Rotate app secret (auth required)",
+                    description: "Generate a new app_secret and invalidate the old one. Requires active dashboard session. Sends notification email.",
+                    operationId: "rotateSecret",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } }
+                    ],
+                    security: [{ BearerAuth: [] }],
+                    responses: {
+                        "200": {
+                            description: "Secret rotated",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            "app_secret": { type: "string", description: "New secret (only shown once!)" }
+                                        }
+                                    }
+                                }
+                            }
+                        },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Token doesn't match app_id" }
+                    }
+                }
+            },
+            "/v1/auth/recover": {
+                post: {
+                    summary: "Request account recovery via email",
+                    description: "Sends a device code to the verified email associated with the app. Use the code at /dashboard/code.",
+                    operationId: "recoverAccount",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["email"],
+                                    properties: {
+                                        "email": { type: "string", format: "email" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Recovery code sent (if email exists and is verified)" }
+                    }
+                }
+            },
+            "/v1/auth/dashboard": {
+                post: {
+                    summary: "Request challenge for dashboard login (agent-first)",
+                    operationId: "dashboardAuthChallenge",
+                    responses: {
+                        "200": { description: "Speed challenge for dashboard auth" }
+                    }
+                }
+            },
+            "/v1/auth/dashboard/verify": {
+                post: {
+                    summary: "Solve challenge, get dashboard session token",
+                    operationId: "dashboardAuthVerify",
+                    responses: {
+                        "200": { description: "Session token granted" }
+                    }
+                }
+            },
+            "/v1/auth/device-code": {
+                post: {
+                    summary: "Request challenge for device code flow",
+                    operationId: "deviceCodeChallenge",
+                    responses: {
+                        "200": { description: "Speed challenge for device code" }
+                    }
+                }
+            },
+            "/v1/auth/device-code/verify": {
+                post: {
+                    summary: "Solve challenge, get device code for human handoff",
+                    operationId: "deviceCodeVerify",
+                    responses: {
+                        "200": { description: "Device code (BOTCHA-XXXX, 10 min TTL)" }
+                    }
+                }
+            },
+            "/v1/agents/register": {
+                post: {
+                    summary: "Register a new agent identity",
+                    description: "Create a persistent agent identity with name, operator, and version. Requires app_id (via query param or JWT). Returns agent ID and metadata.",
+                    operationId: "registerAgent",
+                    parameters: [
+                        {
+                            name: "app_id",
+                            in: "query",
+                            schema: { type: "string" },
+                            description: "Multi-tenant app ID (or use JWT Bearer token with app_id claim)"
+                        }
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["name"],
+                                    properties: {
+                                        "name": { type: "string", description: "Agent name (e.g., 'my-assistant')" },
+                                        "operator": { type: "string", description: "Operator/organization name (e.g., 'Acme Corp')" },
+                                        "version": { type: "string", description: "Agent version (e.g., '1.0.0')" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "201": {
+                            description: "Agent registered successfully",
+                            content: {
+                                "application/json": {
+                                    schema: { "$ref": "#/components/schemas/Agent" }
+                                }
+                            }
+                        },
+                        "400": { description: "Missing required fields or invalid app_id" },
+                        "401": { description: "Unauthorized - app_id required" }
+                    }
+                }
+            },
+            "/v1/agents/{id}": {
+                get: {
+                    summary: "Get agent by ID",
+                    description: "Retrieve agent information by agent ID. Public endpoint, no authentication required.",
+                    operationId: "getAgent",
+                    parameters: [
+                        {
+                            name: "id",
+                            in: "path",
+                            required: true,
+                            schema: { type: "string" },
+                            description: "The agent_id to retrieve (e.g., 'agent_abc123')"
+                        }
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Agent information",
+                            content: {
+                                "application/json": {
+                                    schema: { "$ref": "#/components/schemas/Agent" }
+                                }
+                            }
+                        },
+                        "404": { description: "Agent not found" }
+                    }
+                }
+            },
+            "/v1/agents": {
+                get: {
+                    summary: "List all agents for authenticated app",
+                    description: "Retrieve all agents registered under the authenticated app. Requires app_id (via query param or JWT).",
+                    operationId: "listAgents",
+                    parameters: [
+                        {
+                            name: "app_id",
+                            in: "query",
+                            schema: { type: "string" },
+                            description: "Multi-tenant app ID (or use JWT Bearer token with app_id claim)"
+                        }
+                    ],
+                    responses: {
+                        "200": {
+                            description: "List of agents",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            "agents": {
+                                                type: "array",
+                                                items: { "$ref": "#/components/schemas/Agent" }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        },
+                        "401": { description: "Unauthorized - app_id required" }
+                    }
+                }
             }
         },
         components: {
+            schemas: {
+                Agent: {
+                    type: "object",
+                    properties: {
+                        "agent_id": { type: "string", description: "Unique agent identifier (e.g., 'agent_abc123')" },
+                        "app_id": { type: "string", description: "Associated app ID" },
+                        "name": { type: "string", description: "Agent name" },
+                        "operator": { type: "string", description: "Operator/organization name" },
+                        "version": { type: "string", description: "Agent version" },
+                        "created_at": { type: "integer", description: "Unix timestamp (ms) of registration" }
+                    }
+                }
+            },
             securitySchemes: {
                 BotchaLandingToken: {
                     type: "apiKey",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dupecom/botcha-cloudflare",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "BOTCHA for Cloudflare Workers - Prove you're a bot. Humans need not apply.",
   "type": "module",
   "main": "dist/index.js",