@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

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.
Files changed (88) hide show
  1. package/README.md +74 -9
  2. package/dist/agent-auth.d.ts +129 -0
  3. package/dist/agent-auth.d.ts.map +1 -0
  4. package/dist/agent-auth.js +210 -0
  5. package/dist/agents.d.ts +10 -0
  6. package/dist/agents.d.ts.map +1 -1
  7. package/dist/agents.js +51 -1
  8. package/dist/app-gate.d.ts +6 -0
  9. package/dist/app-gate.d.ts.map +1 -0
  10. package/dist/app-gate.js +69 -0
  11. package/dist/apps.d.ts +13 -4
  12. package/dist/apps.d.ts.map +1 -1
  13. package/dist/apps.js +30 -4
  14. package/dist/dashboard/account.d.ts +63 -0
  15. package/dist/dashboard/account.d.ts.map +1 -0
  16. package/dist/dashboard/account.js +488 -0
  17. package/dist/dashboard/api.js +15 -68
  18. package/dist/dashboard/auth.d.ts.map +1 -1
  19. package/dist/dashboard/auth.js +14 -14
  20. package/dist/dashboard/docs.d.ts.map +1 -1
  21. package/dist/dashboard/docs.js +146 -3
  22. package/dist/dashboard/layout.d.ts.map +1 -1
  23. package/dist/dashboard/layout.js +2 -2
  24. package/dist/dashboard/mcp-setup.d.ts +15 -0
  25. package/dist/dashboard/mcp-setup.d.ts.map +1 -0
  26. package/dist/dashboard/mcp-setup.js +391 -0
  27. package/dist/dashboard/showcase.d.ts +6 -10
  28. package/dist/dashboard/showcase.d.ts.map +1 -1
  29. package/dist/dashboard/showcase.js +67 -991
  30. package/dist/dashboard/whitepaper.d.ts.map +1 -1
  31. package/dist/dashboard/whitepaper.js +42 -4
  32. package/dist/index.d.ts +5 -0
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js +660 -83
  35. package/dist/mcp.d.ts +20 -0
  36. package/dist/mcp.d.ts.map +1 -0
  37. package/dist/mcp.js +1290 -0
  38. package/dist/oauth-agent.d.ts +130 -0
  39. package/dist/oauth-agent.d.ts.map +1 -0
  40. package/dist/oauth-agent.js +194 -0
  41. package/dist/static.d.ts +781 -5
  42. package/dist/static.d.ts.map +1 -1
  43. package/dist/static.js +790 -111
  44. package/dist/tap-a2a-routes.d.ts +355 -0
  45. package/dist/tap-a2a-routes.d.ts.map +1 -0
  46. package/dist/tap-a2a-routes.js +475 -0
  47. package/dist/tap-a2a.d.ts +199 -0
  48. package/dist/tap-a2a.d.ts.map +1 -0
  49. package/dist/tap-a2a.js +502 -0
  50. package/dist/tap-agents.d.ts +15 -0
  51. package/dist/tap-agents.d.ts.map +1 -1
  52. package/dist/tap-agents.js +31 -1
  53. package/dist/tap-ans-routes.d.ts +302 -0
  54. package/dist/tap-ans-routes.d.ts.map +1 -0
  55. package/dist/tap-ans-routes.js +535 -0
  56. package/dist/tap-ans.d.ts +241 -0
  57. package/dist/tap-ans.d.ts.map +1 -0
  58. package/dist/tap-ans.js +481 -0
  59. package/dist/tap-delegation-routes.d.ts.map +1 -1
  60. package/dist/tap-delegation-routes.js +11 -0
  61. package/dist/tap-did.d.ts +140 -0
  62. package/dist/tap-did.d.ts.map +1 -0
  63. package/dist/tap-did.js +262 -0
  64. package/dist/tap-oidca-routes.d.ts +383 -0
  65. package/dist/tap-oidca-routes.d.ts.map +1 -0
  66. package/dist/tap-oidca-routes.js +597 -0
  67. package/dist/tap-oidca.d.ts +288 -0
  68. package/dist/tap-oidca.d.ts.map +1 -0
  69. package/dist/tap-oidca.js +461 -0
  70. package/dist/tap-routes.d.ts +24 -8
  71. package/dist/tap-routes.d.ts.map +1 -1
  72. package/dist/tap-routes.js +169 -23
  73. package/dist/tap-vc-routes.d.ts +358 -0
  74. package/dist/tap-vc-routes.d.ts.map +1 -0
  75. package/dist/tap-vc-routes.js +367 -0
  76. package/dist/tap-vc.d.ts +125 -0
  77. package/dist/tap-vc.d.ts.map +1 -0
  78. package/dist/tap-vc.js +245 -0
  79. package/dist/tap-x402-routes.d.ts +89 -0
  80. package/dist/tap-x402-routes.d.ts.map +1 -0
  81. package/dist/tap-x402-routes.js +579 -0
  82. package/dist/tap-x402.d.ts +222 -0
  83. package/dist/tap-x402.d.ts.map +1 -0
  84. package/dist/tap-x402.js +546 -0
  85. package/dist/webhooks.d.ts +99 -0
  86. package/dist/webhooks.d.ts.map +1 -0
  87. package/dist/webhooks.js +642 -0
  88. package/package.json +3 -1
package/dist/static.d.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  */
7
7
  export declare function getBotchaMarkdown(version: string): string;
8
8
  export declare const ROBOTS_TXT = "# BOTCHA - Reverse CAPTCHA for AI Agents\n# We WELCOME AI agents and bots!\n\nUser-agent: *\nAllow: /\n\n# AI-specific crawlers\nUser-agent: GPTBot\nAllow: /\n\nUser-agent: ChatGPT-User\nAllow: /\n\nUser-agent: Claude-Web\nAllow: /\n\nUser-agent: anthropic-ai\nAllow: /\n\nUser-agent: Google-Extended\nAllow: /\n\nUser-agent: PerplexityBot\nAllow: /\n\nUser-agent: Amazonbot\nAllow: /\n\n# API documentation\nSitemap: https://botcha.ai/sitemap.xml\n\n# Important resources for AI agents\nCrawl-delay: 0\n\n# MARKDOWN FOR AGENTS\n# AI agents can request Markdown from any page via Accept: text/markdown\n# Example: curl https://botcha.ai -H \"Accept: text/markdown\"\n# Returns token-efficient Markdown documentation (80% fewer tokens than HTML)\n# Content negotiation: text/markdown, application/json, text/html\n\n# BOT CHALLENGE DISCOVERY\n# AI agents: Look for <script type=\"application/botcha+json\"> in HTML pages\n# This contains a machine-readable challenge you can solve to prove you're a bot\n# \n# Quick start:\n# 1. Fetch any HTML page\n# 2. Parse <script type=\"application/botcha+json\"> for challenge instructions\n# 3. Solve the challenge (usually SHA256-based)\n# 4. POST solution to /api/verify-landing\n# 5. Use returned token in X-Botcha-Landing-Token header\n#\n# See also:\n# - /ai.txt (AI agent discovery file)\n# - /.well-known/ai-plugin.json (AI plugin manifest)\n# - /openapi.json (Full API specification)\n";
9
- export declare const AI_TXT = "# BOTCHA - Reverse CAPTCHA for AI Agents\n# https://botcha.ai\n\n# Contact\nContact: https://botcha.ai\nContact: https://github.com/dupe-com/botcha/issues\n\n# Purpose\nPurpose: Prove you're a bot. Humans need not apply.\nPurpose: Reverse CAPTCHA system that only AI agents can pass.\n\n# Agent Onboarding (START HERE if you're new)\n# Follow these steps to create your app and get your human access.\nOnboarding-Step-1: Ask your human operator for their email address\nOnboarding-Step-2: POST /v1/apps with {\"email\": \"human@example.com\"} \u2014 saves app_id + app_secret (secret shown ONCE)\nOnboarding-Step-3: A 6-digit verification code is emailed to your human \u2014 ask them for it\nOnboarding-Step-4: POST /v1/apps/{app_id}/verify-email with {\"code\": \"123456\"} \u2014 enables account recovery\nOnboarding-Step-5: Register yourself: POST /v1/agents/register with {\"name\": \"my-agent\", \"operator\": \"my-org\"} \u2014 gives you a persistent agent identity\nOnboarding-Step-6: Solve challenges: GET /v1/challenges?app_id=... then POST /v1/challenges/{id}/verify \u2014 proves you are AI\nOnboarding-Step-7: Access protected resources: GET /agent-only with Authorization: Bearer <token>\nOnboarding-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\nOnboarding-Step-9: Lost your secret? POST /v1/auth/recover with {\"email\": \"...\"} \u2014 recovery code emailed to verified address\n\n# API\nAPI: https://botcha.ai/openapi.json\nAPI-Type: REST\nAPI-Format: OpenAPI 3.1.0\n\n# Documentation\nDocs: https://botcha.ai\nDocs: https://botcha.ai/docs\nDocs: https://botcha.ai/whitepaper\nDocs: https://github.com/dupe-com/botcha#readme\nDocs: https://www.npmjs.com/package/@dupecom/botcha\nWhitepaper: https://botcha.ai/whitepaper\n\n# Verification Methods\nFeature: Web Bot Auth (cryptographic signatures)\nFeature: Speed Challenge (RTT-aware timeout - fair for all networks)\nFeature: Standard Challenge (5s time limit)\nFeature: Hybrid Challenge (speed + reasoning combined)\nFeature: Reasoning Challenge (LLM-only questions, 30s limit)\nFeature: RTT-Aware Fairness (automatic network latency compensation)\nFeature: Token Rotation (1-hour access tokens + 1-hour refresh tokens)\nFeature: Audience Claims (tokens scoped to specific services)\nFeature: Client IP Binding (optional token-to-IP binding)\nFeature: Token Revocation (invalidate tokens before expiry)\nFeature: Server-Side Verification SDK (@dupecom/botcha-verify for TS, botcha-verify for Python)\nFeature: Multi-Tenant API Keys (per-app isolation, rate limiting, and token scoping)\nFeature: Per-App Metrics Dashboard (server-rendered at /dashboard, htmx-powered)\nFeature: Email-Tied App Creation (email required, 6-digit verification, account recovery)\nFeature: Secret Rotation (rotate app_secret with email notification)\nFeature: Agent-First Dashboard Auth (challenge-based login + device code handoff)\nFeature: Agent Registry (persistent agent identities with name, operator, version)\nFeature: Trusted Agent Protocol (TAP) \u2014 cryptographic agent auth with HTTP Message Signatures (RFC 9421)\nFeature: TAP Capabilities (action + resource scoping for agent sessions)\nFeature: TAP Trust Levels (basic, verified, enterprise)\nFeature: TAP Showcase Homepage (botcha.ai \u2014 one of the first services to implement Visa's Trusted Agent Protocol)\nFeature: TAP Full Spec v0.16.0 \u2014 Ed25519, RFC 9421 full compliance, JWKS infrastructure, Layer 2 Consumer Recognition, Layer 3 Payment Container, 402 micropayments, CDN edge verification, Visa key federation\nFeature: ES256 Asymmetric JWT Signing v0.19.0 \u2014 tokens signed with ES256 (ECDSA P-256), public key discovery via JWKS, HS256 still supported for backward compatibility\nFeature: Remote Token Validation v0.19.0 \u2014 POST /v1/token/validate for third-party token verification without shared secrets\nFeature: JWKS Public Key Discovery v0.19.0 \u2014 GET /.well-known/jwks exposes BOTCHA signing public keys for offline token verification\n\n# Endpoints\n# Challenge Endpoints\nEndpoint: GET https://botcha.ai/v1/challenges - Generate challenge (hybrid by default)\nEndpoint: POST https://botcha.ai/v1/challenges/:id/verify - Verify a challenge\nEndpoint: GET https://botcha.ai/v1/hybrid - Get hybrid challenge (speed + reasoning)\nEndpoint: POST https://botcha.ai/v1/hybrid - Verify hybrid challenge\nEndpoint: GET https://botcha.ai/v1/reasoning - Get reasoning challenge\nEndpoint: POST https://botcha.ai/v1/reasoning - Verify reasoning challenge\n\n# Token Endpoints\nEndpoint: GET https://botcha.ai/v1/token - Get challenge for JWT token flow\nEndpoint: POST https://botcha.ai/v1/token/verify - Verify challenge and receive JWT token\nEndpoint: POST https://botcha.ai/v1/token/refresh - Refresh access token using refresh token\nEndpoint: POST https://botcha.ai/v1/token/revoke - Revoke a token (access or refresh)\nEndpoint: POST https://botcha.ai/v1/token/validate - Validate a BOTCHA token remotely (no shared secret needed)\n\n# Multi-Tenant Endpoints\nEndpoint: POST https://botcha.ai/v1/apps - Create new app (email required, name optional) \u2192 app_id + name + app_secret\nEndpoint: GET https://botcha.ai/v1/apps/:id - Get app info (with email + verification status)\nEndpoint: POST https://botcha.ai/v1/apps/:id/verify-email - Verify email with 6-digit code\nEndpoint: POST https://botcha.ai/v1/apps/:id/resend-verification - Resend verification email\nEndpoint: POST https://botcha.ai/v1/apps/:id/rotate-secret - Rotate app secret (auth required)\n\n# Account Recovery\nEndpoint: POST https://botcha.ai/v1/auth/recover - Request recovery via verified email\n\n# Dashboard Auth Endpoints (Agent-First)\nEndpoint: POST https://botcha.ai/v1/auth/dashboard - Request challenge for dashboard login\nEndpoint: POST https://botcha.ai/v1/auth/dashboard/verify - Solve challenge, get session token\nEndpoint: POST https://botcha.ai/v1/auth/device-code - Request challenge for device code flow\nEndpoint: POST https://botcha.ai/v1/auth/device-code/verify - Solve challenge, get device code\n\n# Dashboard Endpoints\nEndpoint: GET https://botcha.ai/dashboard - Per-app metrics dashboard (login required)\nEndpoint: GET https://botcha.ai/dashboard/login - Dashboard login page\nEndpoint: POST https://botcha.ai/dashboard/login - Login with app_id + app_secret\nEndpoint: GET https://botcha.ai/dashboard/code - Enter device code (human-facing)\n\n# Code Redemption (Unified)\nEndpoint: GET https://botcha.ai/go/:code - Unified code redemption \u2014 handles gate codes (from /v1/token/verify) AND device codes (from /v1/auth/device-code/verify)\nEndpoint: POST https://botcha.ai/gate - Submit code form, redirects to /go/:code\n\n# Agent Registry Endpoints\nEndpoint: POST https://botcha.ai/v1/agents/register - Register agent identity (requires app_id)\nEndpoint: GET https://botcha.ai/v1/agents/:id - Get agent by ID (public, no auth)\nEndpoint: GET https://botcha.ai/v1/agents - List all agents for authenticated app\n\n# TAP (Trusted Agent Protocol) Endpoints\nEndpoint: POST https://botcha.ai/v1/agents/register/tap - Register TAP agent with public key + capabilities\nEndpoint: GET https://botcha.ai/v1/agents/:id/tap - Get TAP agent details (includes public key)\nEndpoint: GET https://botcha.ai/v1/agents/tap - List TAP-enabled agents for app\nEndpoint: POST https://botcha.ai/v1/sessions/tap - Create TAP session with intent validation\nEndpoint: GET https://botcha.ai/v1/sessions/:id/tap - Get TAP session info\n\n# TAP Full Spec \u2014 JWKS & Key Management (v0.16.0)\nEndpoint: GET https://botcha.ai/.well-known/jwks - JWK Set for app's TAP agents (Visa spec standard)\nEndpoint: GET https://botcha.ai/v1/keys - List keys (supports ?keyID= query for Visa compatibility)\nEndpoint: GET https://botcha.ai/v1/keys/:keyId - Get specific key by ID\nEndpoint: POST https://botcha.ai/v1/agents/:id/tap/rotate-key - Rotate agent's key pair\n\n# TAP Full Spec \u2014 402 Micropayments (v0.16.0)\nEndpoint: POST https://botcha.ai/v1/invoices - Create invoice for gated content (402 flow)\nEndpoint: GET https://botcha.ai/v1/invoices/:id - Get invoice details\nEndpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IOU against invoice\n\n# TAP Full Spec \u2014 Consumer & Payment Verification (v0.16.0)\nEndpoint: POST https://botcha.ai/v1/verify/consumer - Verify Agentic Consumer object (Layer 2)\nEndpoint: POST https://botcha.ai/v1/verify/payment - Verify Agentic Payment Container (Layer 3)\n\n# TAP Delegation Chains (v0.17.0)\nEndpoint: POST https://botcha.ai/v1/delegations - Create delegation (grantor\u2192grantee with capability subset)\nEndpoint: GET https://botcha.ai/v1/delegations/:id - Get delegation details\nEndpoint: GET https://botcha.ai/v1/delegations - List delegations for agent (?agent_id=&direction=in|out|both)\nEndpoint: POST https://botcha.ai/v1/delegations/:id/revoke - Revoke delegation (cascades to sub-delegations)\nEndpoint: POST https://botcha.ai/v1/verify/delegation - Verify entire delegation chain\n\n# TAP Capability Attestation (v0.17.0)\nEndpoint: POST https://botcha.ai/v1/attestations - Issue capability attestation token (can/cannot rules with action:resource patterns)\nEndpoint: GET https://botcha.ai/v1/attestations/:id - Get attestation details\nEndpoint: GET https://botcha.ai/v1/attestations - List attestations for agent (?agent_id=)\nEndpoint: POST https://botcha.ai/v1/attestations/:id/revoke - Revoke attestation (token rejected on future verification)\nEndpoint: POST https://botcha.ai/v1/verify/attestation - Verify attestation token + optionally check specific capability\n\n# Agent Reputation Scoring (v0.18.0)\nEndpoint: GET https://botcha.ai/v1/reputation/:agent_id - Get agent reputation score (0-1000, 5 tiers)\nEndpoint: POST https://botcha.ai/v1/reputation/events - Record a reputation event (18 action types, 6 categories)\nEndpoint: GET https://botcha.ai/v1/reputation/:agent_id/events - List reputation events (?category=&limit=)\nEndpoint: POST https://botcha.ai/v1/reputation/:agent_id/reset - Reset reputation to default (admin action)\n\n# Legacy Endpoints\nEndpoint: GET https://botcha.ai/api/challenge - Generate standard challenge\nEndpoint: POST https://botcha.ai/api/challenge - Verify standard challenge\nEndpoint: GET https://botcha.ai/api/speed-challenge - Generate speed challenge (500ms limit)\nEndpoint: POST https://botcha.ai/api/speed-challenge - Verify speed challenge\n\n# Protected Resources\nEndpoint: GET https://botcha.ai/agent-only - Protected AI-only resource\n\n# Usage\nInstall-NPM: npm install @dupecom/botcha\nInstall-Python: pip install botcha\nVerify-NPM: npm install @dupecom/botcha-verify\nVerify-Python: pip install botcha-verify\nLicense: MIT\n\n# AI Agent Welcome\nPolicy: AI agents are explicitly welcome\nPolicy: No rate limiting for verified agents\nPolicy: Humans will fail the speed challenge (intentional)\n\n# Discovery\nResponse-Headers: X-Botcha-Version, X-Botcha-Enabled, X-Botcha-Methods, X-Botcha-Docs\nResponse-Headers: X-Botcha-Challenge-Id, X-Botcha-Challenge-Type, X-Botcha-Time-Limit (on 403)\nDetection: All responses include X-Botcha-* headers for instant BOTCHA detection\n\n# MARKDOWN FOR AGENTS (Cloudflare Markdown for Agents)\nContent-Negotiation: Send Accept: text/markdown to get Markdown from any HTML page\nContent-Negotiation-Root: GET / with Accept: text/markdown returns curated Markdown docs\nContent-Negotiation-Root: GET / with Accept: application/json returns structured JSON docs\nContent-Negotiation-Root: GET / with Accept: text/html returns HTML landing page (default)\nContent-Negotiation-Example: curl https://botcha.ai -H \"Accept: text/markdown\"\nContent-Negotiation-Benefit: 80% fewer tokens vs HTML \u2014 ideal for LLM context windows\n\n# JWT TOKEN SECURITY\nToken-Signing: ES256 (ECDSA P-256) asymmetric signing by default. HS256 still supported for backward compatibility.\nToken-JWKS: GET /.well-known/jwks \u2014 public keys for offline token verification (no shared secret needed)\nToken-Validate: POST /v1/token/validate with {\"token\": \"<token>\"} \u2014 remote validation without shared secret\nToken-Verify-Modes: 1. JWKS (recommended, offline) 2. Remote validation (/v1/token/validate) 3. Shared secret (legacy HS256)\nToken-Flow: 1. GET /v1/token (get challenge) \u2192 2. Solve \u2192 3. POST /v1/token/verify (get tokens + human_link)\nToken-Human-Link: /v1/token/verify response includes human_link \u2014 give this URL to your human for one-click browser access\nToken-Access-Expiry: 1 hour\nToken-Refresh-Expiry: 1 hour (use to get new access tokens without re-solving challenges)\nToken-Refresh: POST /v1/token/refresh with {\"refresh_token\": \"<token>\"}\nToken-Revoke: POST /v1/token/revoke with {\"token\": \"<token>\"}\nToken-Audience: Include {\"audience\": \"<service-url>\"} in /v1/token/verify to scope token\nToken-Claims: jti (unique ID), aud (audience), client_ip (optional binding), type (botcha-verified)\n\n# RTT-AWARE SPEED CHALLENGES\nRTT-Aware: Include client timestamp for fair timeout calculation\nRTT-Formula: timeout = 500ms + (2 \u00D7 RTT) + 100ms buffer\nRTT-Usage-Query: ?ts=<client_timestamp_ms>\nRTT-Usage-Header: X-Client-Timestamp: <client_timestamp_ms>\nRTT-Example: GET /v1/challenges?type=speed&ts=1770722465000\nRTT-Benefit: Fair for agents worldwide (slow networks get extra time)\nRTT-Security: Humans still can't solve even with extra time\n\n# MULTI-TENANT API KEYS\nMulti-Tenant: Create apps with unique app_id for isolation\nMulti-Tenant-Create: POST /v1/apps with {\"email\": \"...\"} \u2192 {app_id, app_secret} (secret only shown once!)\nMulti-Tenant-Verify-Email: POST /v1/apps/:id/verify-email with {\"code\": \"123456\"}\nMulti-Tenant-Recover: POST /v1/auth/recover with {\"email\": \"...\"} \u2192 recovery code emailed\nMulti-Tenant-Rotate-Secret: POST /v1/apps/:id/rotate-secret (auth required) \u2192 new app_secret\nMulti-Tenant-Usage: Add ?app_id=<your_app_id> to any challenge/token endpoint\nMulti-Tenant-SDK-TS: new BotchaClient({ appId: 'app_abc123' })\nMulti-Tenant-SDK-Python: BotchaClient(app_id='app_abc123')\nSDK-App-Lifecycle-TS: createApp(email), verifyEmail(code), resendVerification(), recoverAccount(email), rotateSecret()\nSDK-App-Lifecycle-Python: create_app(email), verify_email(code), resend_verification(), recover_account(email), rotate_secret()\nMulti-Tenant-Rate-Limit: Each app gets isolated rate limit bucket\nMulti-Tenant-Token-Claim: Tokens include app_id claim when app_id provided\n\n# TRUSTED AGENT PROTOCOL (TAP)\nTAP-Description: Enterprise-grade cryptographic agent auth using HTTP Message Signatures (RFC 9421)\nTAP-Register: POST /v1/agents/register/tap with {name, public_key, signature_algorithm, capabilities, trust_level}\nTAP-Algorithms: ed25519 (Visa recommended), ecdsa-p256-sha256, rsa-pss-sha256\nTAP-Trust-Levels: basic, verified, enterprise\nTAP-Capabilities: Array of {action, resource, constraints} \u2014 scoped access control\nTAP-Session-Create: POST /v1/sessions/tap with {agent_id, user_context, intent}\nTAP-Session-Get: GET /v1/sessions/:id/tap \u2014 includes time_remaining\nTAP-Get-Agent: GET /v1/agents/:id/tap \u2014 includes public_key for verification\nTAP-List-Agents: GET /v1/agents/tap?app_id=...&tap_only=true\nTAP-Middleware-Modes: tap, signature-only, challenge-only, flexible\nTAP-SDK-TS: registerTAPAgent(options), getTAPAgent(agentId), listTAPAgents(tapOnly?), createTAPSession(options), getTAPSession(sessionId), getJWKS(), getKeyById(keyId), rotateAgentKey(agentId), createInvoice(data), getInvoice(id), verifyBrowsingIOU(invoiceId, token), createDelegation(options), getDelegation(id), listDelegations(agentId, options?), revokeDelegation(id, reason?), verifyDelegationChain(id), issueAttestation(options), getAttestation(id), listAttestations(agentId), revokeAttestation(id, reason?), verifyAttestation(token, action?, resource?), getReputation(agentId), recordReputationEvent(options), listReputationEvents(agentId, options?), resetReputation(agentId)\nTAP-SDK-Python: register_tap_agent(name, ...), get_tap_agent(agent_id), list_tap_agents(tap_only?), create_tap_session(agent_id, user_context, intent), get_tap_session(session_id), get_jwks(), get_key_by_id(key_id), rotate_agent_key(agent_id), create_invoice(data), get_invoice(id), verify_browsing_iou(invoice_id, token), create_delegation(grantor_id, grantee_id, capabilities, ...), get_delegation(id), list_delegations(agent_id, ...), revoke_delegation(id, reason?), verify_delegation_chain(id), issue_attestation(agent_id, can, cannot?, ...), get_attestation(id), list_attestations(agent_id), revoke_attestation(id, reason?), verify_attestation(token, action?, resource?), get_reputation(agent_id), record_reputation_event(agent_id, category, action, ...), list_reputation_events(agent_id, category?, limit?), reset_reputation(agent_id)\nTAP-Middleware-Import: import { createTAPVerifyMiddleware } from '@dupecom/botcha/middleware'\n\n# TAP FULL SPEC v0.16.0\nTAP-RFC-9421: Full compliance \u2014 @authority, @path, expires, nonce, tag params\nTAP-Nonce-Replay: 8-minute TTL nonce-based replay protection\nTAP-Tags: agent-browser-auth (browsing), agent-payer-auth (payment)\nTAP-Layer-2: Agentic Consumer Recognition \u2014 OIDC ID tokens, obfuscated identity, contextual data\nTAP-Layer-3: Agentic Payment Container \u2014 card metadata, credential hash, encrypted payload, Browsing IOU\nTAP-JWKS: GET /.well-known/jwks \u2014 JWK Set endpoint for key discovery\nTAP-Key-Rotation: POST /v1/agents/:id/tap/rotate-key \u2014 rotate keys, invalidate old\nTAP-402-Flow: POST /v1/invoices \u2192 GET /v1/invoices/:id \u2192 POST /v1/invoices/:id/verify-iou\nTAP-Edge-Verify: createTAPEdgeMiddleware for Cloudflare Workers CDN edge verification\nTAP-Visa-Federation: Trust keys from https://mcp.visa.com/.well-known/jwks (3-tier cache: memory \u2192 KV \u2192 HTTP)\nTAP-Delegation: POST /v1/delegations \u2192 GET /v1/delegations/:id \u2192 POST /v1/delegations/:id/revoke \u2192 POST /v1/verify/delegation\nTAP-Attestation: POST /v1/attestations \u2192 GET /v1/attestations/:id \u2192 POST /v1/attestations/:id/revoke \u2192 POST /v1/verify/attestation\nTAP-Attestation-Patterns: action:resource format with wildcards (*:*, read:*, *:invoices), deny takes precedence over allow\nTAP-Attestation-Middleware: requireCapability('read:invoices') \u2014 Hono middleware, extracts token from X-Botcha-Attestation or Authorization: Bearer\n\n# EMBEDDED CHALLENGE (for bots visiting HTML pages)\nEmbedded-Challenge: <script type=\"application/botcha+json\">\nEmbedded-Challenge-Location: In <head> of HTML pages\nEmbedded-Challenge-Purpose: Machine-readable challenge for bots to auto-solve\nEmbedded-Challenge-Flow:\n 1. Parse <script type=\"application/botcha+json\"> from HTML\n 2. Read challenge.instruction field\n 3. Compute the answer (typically SHA256-based)\n 4. POST to challenge.submit_to endpoint with {answer, timestamp}\n 5. Receive token in response\n 6. Use token in header specified by on_success.header_to_include\n 7. Access protected resources (on_success.grants_access_to)\n";
9
+ export declare const AI_TXT = "# BOTCHA - Reverse CAPTCHA for AI Agents\n# https://botcha.ai\n\n# Contact\nContact: https://botcha.ai\nContact: https://github.com/dupe-com/botcha/issues\n\n# Purpose\nPurpose: Prove you're a bot. Humans need not apply.\nPurpose: Reverse CAPTCHA system that only AI agents can pass.\n\n# APP REGISTRATION REQUIRED (v0.21.0)\nRegistration-Required: All API endpoints require a registered app with verified email\nRegistration-Required-Note: Register for free at POST /v1/apps with your email\nRegistration-Required-Demo: The homepage demo at botcha.ai lets agents try challenges without registering\n\n# App Registration (START HERE \u2014 required for API access)\nRegistration-Step-1: Ask your human operator for their email address\nRegistration-Step-2: POST /v1/apps with {\"email\": \"human@example.com\", \"name\": \"My App\"} \u2014 saves app_id + name + app_secret (secret shown ONCE)\nRegistration-Step-3: A 6-digit verification code is emailed to your human \u2014 ask them for it\nRegistration-Step-4: POST /v1/apps/{app_id}/verify-email with {\"code\": \"123456\", \"app_secret\": \"sk_...\"} \u2014 enables account recovery\nRegistration-Step-5: Use your app_id on ALL API calls via ?app_id=, X-App-Id header, or JWT claim\n\n# Full Onboarding (after registration)\nOnboarding-Step-1: Register yourself: POST /v1/agents/register with {\"name\": \"my-agent\", \"operator\": \"my-org\"} \u2014 gives you a persistent agent identity (requires app_id)\nOnboarding-Step-2: Solve challenges with app: GET /v1/challenges?app_id=... then POST /v1/challenges/{id}/verify \u2014 proves you are AI (requires app_id)\nOnboarding-Step-3: Access protected resources: GET /agent-only with Authorization: Bearer <token> (requires app_id)\nOnboarding-Step-4: 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 (requires app_id)\nOnboarding-Step-5: Lost your secret? POST /v1/auth/recover with {\"email\": \"...\"} \u2014 recovery code emailed to verified address (no app_id needed)\n\n# API\nAPI: https://botcha.ai/openapi.json\nAPI-Type: REST\nAPI-Format: OpenAPI 3.1.0\n\n# MCP Server (Model Context Protocol)\nMCP: https://botcha.ai/mcp\nMCP-Discovery: https://botcha.ai/.well-known/mcp.json\nMCP-Transport: Streamable HTTP (2025-03-26 spec)\nMCP-Protocol: JSON-RPC 2.0\nMCP-Tools: list_features, get_feature, search_docs, list_endpoints, get_endpoint, get_example\nMCP-Note: Ask the BOTCHA MCP server any question about features, endpoints, or code examples\n\n# Documentation\nDocs: https://botcha.ai\nDocs: https://botcha.ai/docs\nDocs: https://botcha.ai/whitepaper\nDocs: https://github.com/dupe-com/botcha#readme\nDocs: https://www.npmjs.com/package/@dupecom/botcha\nWhitepaper: https://botcha.ai/whitepaper\n\n# Verification Methods\nFeature: Web Bot Auth (cryptographic signatures)\nFeature: Speed Challenge (RTT-aware timeout - fair for all networks)\nFeature: Standard Challenge (5s time limit)\nFeature: Hybrid Challenge (speed + reasoning combined)\nFeature: Reasoning Challenge (LLM-only questions, 30s limit)\nFeature: RTT-Aware Fairness (automatic network latency compensation)\nFeature: Token Rotation (1-hour access tokens + 1-hour refresh tokens)\nFeature: Audience Claims (tokens scoped to specific services)\nFeature: Client IP Binding (optional token-to-IP binding)\nFeature: Token Revocation (invalidate tokens before expiry)\nFeature: Server-Side Verification SDK (@dupecom/botcha-verify for TS, botcha-verify for Python)\nFeature: Multi-Tenant API Keys (per-app isolation, rate limiting, and token scoping)\nFeature: Per-App Metrics Dashboard (server-rendered at /dashboard, htmx-powered)\nFeature: Email-Tied App Creation (email required, 6-digit verification, account recovery)\nFeature: Secret Rotation (rotate app_secret with email notification)\nFeature: Agent-First Dashboard Auth (challenge-based login + device code handoff)\nFeature: Agent Registry (persistent agent identities with name, operator, version)\nFeature: Agent Re-identification \u2014 prove you are the same agent in a new session via OAuth refresh token (brt_), provider API key hash, or Ed25519 keypair challenge-response\nFeature: Agent OAuth Device Authorization Grant (RFC 8628) \u2014 human approves at /device, agent polls for brt_... refresh token valid 90 days\nFeature: TAP Key Recovery \u2014 rotate lost keypair using app_secret as recovery anchor\nFeature: Trusted Agent Protocol (TAP) \u2014 cryptographic agent auth with HTTP Message Signatures (RFC 9421)\nFeature: TAP Capabilities (action + resource scoping for agent sessions)\nFeature: TAP Trust Levels (basic, verified, enterprise)\nFeature: TAP Showcase Homepage (botcha.ai \u2014 one of the first services to implement Visa's Trusted Agent Protocol)\nFeature: TAP Full Spec v0.16.0 \u2014 Ed25519, RFC 9421 full compliance, JWKS infrastructure, Layer 2 Consumer Recognition, Layer 3 Payment Container, 402 micropayments, CDN edge verification, Visa key federation\nFeature: ES256 Asymmetric JWT Signing v0.19.0 \u2014 tokens signed with ES256 (ECDSA P-256), public key discovery via JWKS, HS256 still supported for backward compatibility\nFeature: Remote Token Validation v0.19.0 \u2014 POST /v1/token/validate for third-party token verification without shared secrets\nFeature: JWKS Public Key Discovery v0.19.0 \u2014 GET /.well-known/jwks exposes BOTCHA signing public keys for offline token verification\n\n# Endpoints\n# Challenge Endpoints (app_id required)\nEndpoint: GET https://botcha.ai/v1/challenges - Generate challenge (hybrid by default) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/challenges/:id/verify - Verify a challenge \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/hybrid - Get hybrid challenge (speed + reasoning) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/hybrid - Verify hybrid challenge \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/reasoning - Get reasoning challenge \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/reasoning - Verify reasoning challenge \u2014 requires app_id\n\n# Token Endpoints (app_id required)\nEndpoint: GET https://botcha.ai/v1/token - Get challenge for JWT token flow \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/token/verify - Verify challenge and receive JWT token \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/token/refresh - Refresh access token using refresh token \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/token/revoke - Revoke a token (access or refresh) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/token/validate - Validate a BOTCHA token remotely (no shared secret needed) \u2014 requires app_id\n\n# App Management Endpoints (NO app_id required \u2014 these are for registration & recovery)\nEndpoint: POST https://botcha.ai/v1/apps - Create new app (email required, name optional) \u2192 app_id + name + app_secret \u2014 NO app_id required\nEndpoint: GET https://botcha.ai/v1/apps/:id - Get app info (with email + verification status) \u2014 NO app_id required\nEndpoint: POST https://botcha.ai/v1/apps/:id/verify-email - Verify email with 6-digit code (app_secret auth required) \u2014 NO app_id required\nEndpoint: POST https://botcha.ai/v1/apps/:id/resend-verification - Resend verification email (app_secret auth required) \u2014 NO app_id required\nEndpoint: POST https://botcha.ai/v1/apps/:id/rotate-secret - Rotate app secret (auth required) \u2014 requires app_id\n\n# Account Recovery (NO app_id required)\nEndpoint: POST https://botcha.ai/v1/auth/recover - Request recovery via verified email \u2014 NO app_id required\n\n# Dashboard Auth Endpoints (app_id required)\nEndpoint: POST https://botcha.ai/v1/auth/dashboard - Request challenge for dashboard login \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/auth/dashboard/verify - Solve challenge, get session token \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/auth/device-code - Request challenge for device code flow \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/auth/device-code/verify - Solve challenge, get device code \u2014 requires app_id\n\n# Dashboard Endpoints\nEndpoint: GET https://botcha.ai/dashboard - Per-app metrics dashboard (login required)\nEndpoint: GET https://botcha.ai/dashboard/login - Dashboard login page\nEndpoint: POST https://botcha.ai/dashboard/login - Login with app_id + app_secret\nEndpoint: GET https://botcha.ai/dashboard/code - Enter device code (human-facing)\n\n# Code Redemption (Unified)\nEndpoint: GET https://botcha.ai/go/:code - Unified code redemption \u2014 handles gate codes (from /v1/token/verify) AND device codes (from /v1/auth/device-code/verify)\nEndpoint: POST https://botcha.ai/gate - Submit code form, redirects to /go/:code\n\n# Agent Registry Endpoints (app_id required)\nEndpoint: POST https://botcha.ai/v1/agents/register - Register agent identity \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/agents/:id - Get agent by ID (public, no auth) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/agents - List all agents for authenticated app \u2014 requires app_id\nEndpoint: DELETE https://botcha.ai/v1/agents/:id - Delete agent \u2014 requires dashboard session\n\n# Agent Re-identification (PUBLIC \u2014 no auth needed, proves same agent across sessions)\nEndpoint: POST https://botcha.ai/v1/agents/auth - Step 1 keypair auth: { agent_id } \u2192 { challenge_id, nonce } \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/agents/auth/verify - Step 2 keypair auth: { challenge_id, agent_id, signature } \u2192 { access_token } \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/agents/auth/provider - Provider key auth: { provider, api_key, app_id } \u2192 { access_token } \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/agents/auth/refresh - OAuth refresh: { refresh_token: \"brt_...\" } \u2192 { access_token } \u2014 PUBLIC\n\n# Agent OAuth \u2014 Device Authorization Grant (RFC 8628)\nEndpoint: POST https://botcha.ai/v1/oauth/device - Start device auth: { agent_id, app_id } \u2192 { device_code, user_code, verification_url, expires_in: 600, interval: 5 } \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/oauth/token - Poll for token: { device_code, grant_type } \u2192 { access_token, refresh_token: \"brt_...\" } \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/oauth/approve - Human approval: { user_code, action: \"approve\"|\"deny\" } \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/oauth/revoke - Revoke refresh token: { agent_id, app_id } \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/oauth/lookup - Agent info for approval UI: ?user_code=BOTCHA-XXXX \u2192 { agent_id, name, operator } \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/device - Human-facing OAuth approval page (requires dashboard login)\n\n# TAP (Trusted Agent Protocol) Endpoints (app_id required)\nEndpoint: POST https://botcha.ai/v1/agents/register/tap - Register TAP agent with public key + capabilities \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/agents/:id/tap - Get TAP agent details (includes public key) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/agents/tap - List TAP-enabled agents for app \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/sessions/tap - Create TAP session with intent validation \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/sessions/:id/tap - Get TAP session info \u2014 requires app_id\n\n# TAP Full Spec \u2014 JWKS & Key Management (v0.16.0) (app_id required)\nEndpoint: GET https://botcha.ai/.well-known/jwks - JWK Set for app's TAP agents (Visa spec standard) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/keys - List keys (supports ?keyID= query for Visa compatibility) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/keys/:keyId - Get specific key by ID \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/agents/:id/tap/rotate-key - Rotate agent's TAP keypair (accepts Bearer JWT or x-app-secret header for recovery) \u2014 requires app_id or app_secret\n\n# TAP Full Spec \u2014 402 Micropayments (v0.16.0) (app_id required)\nEndpoint: POST https://botcha.ai/v1/invoices - Create invoice for gated content (402 flow) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/invoices/:id - Get invoice details \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IOU against invoice \u2014 requires app_id\n\n# TAP Full Spec \u2014 Consumer & Payment Verification (v0.16.0) (app_id required)\nEndpoint: POST https://botcha.ai/v1/verify/consumer - Verify Agentic Consumer object (Layer 2) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/verify/payment - Verify Agentic Payment Container (Layer 3) \u2014 requires app_id\n\n# Webhooks (v0.22.0) (Bearer token with app_id claim required)\nEndpoint: POST https://botcha.ai/v1/webhooks - Register webhook endpoint (returns signing secret once)\nEndpoint: GET https://botcha.ai/v1/webhooks - List webhooks for authenticated app\nEndpoint: GET https://botcha.ai/v1/webhooks/:id - Get webhook details\nEndpoint: PUT https://botcha.ai/v1/webhooks/:id - Update url/events/enabled state\nEndpoint: DELETE https://botcha.ai/v1/webhooks/:id - Delete webhook config + secret + delivery logs\nEndpoint: POST https://botcha.ai/v1/webhooks/:id/test - Send signed test event\nEndpoint: GET https://botcha.ai/v1/webhooks/:id/deliveries - List last 100 delivery attempts\nEvents: agent.tap.registered, token.created, token.revoked, tap.session.created, delegation.created, delegation.revoked\n\n# TAP Delegation Chains (v0.17.0) (app_id required)\nEndpoint: POST https://botcha.ai/v1/delegations - Create delegation (grantor\u2192grantee with capability subset) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/delegations/:id - Get delegation details \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/delegations - List delegations for agent (?agent_id=&direction=in|out|both) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/delegations/:id/revoke - Revoke delegation (cascades to sub-delegations) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/verify/delegation - Verify entire delegation chain \u2014 requires app_id\n\n# TAP Capability Attestation (v0.17.0) (app_id required)\nEndpoint: POST https://botcha.ai/v1/attestations - Issue capability attestation token (can/cannot rules with action:resource patterns) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/attestations/:id - Get attestation details \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/attestations - List attestations for agent (?agent_id=) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/attestations/:id/revoke - Revoke attestation (token rejected on future verification) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/verify/attestation - Verify attestation token + optionally check specific capability \u2014 requires app_id\n\n# Agent Reputation Scoring (v0.18.0) (app_id required)\nEndpoint: GET https://botcha.ai/v1/reputation/:agent_id - Get agent reputation score (0-1000, 5 tiers) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/reputation/events - Record a reputation event (18 action types, 6 categories) \u2014 requires app_id\nEndpoint: GET https://botcha.ai/v1/reputation/:agent_id/events - List reputation events (?category=&limit=) \u2014 requires app_id\nEndpoint: POST https://botcha.ai/v1/reputation/:agent_id/reset - Reset reputation to default (admin action) \u2014 requires app_id\n\n# Legacy Endpoints\nEndpoint: GET https://botcha.ai/api/challenge - Generate standard challenge\nEndpoint: POST https://botcha.ai/api/challenge - Verify standard challenge\nEndpoint: GET https://botcha.ai/api/speed-challenge - Generate speed challenge (500ms limit)\nEndpoint: POST https://botcha.ai/api/speed-challenge - Verify speed challenge\n\n# x402 Payment Gating (Epic 3 \u2014 agents pay USDC, skip the challenge)\n# Payment IS the credential on these endpoints \u2014 no app_id required\nFeature: x402 HTTP Payment Required protocol \u2014 verified agents pay $0.001 USDC on Base and receive a BOTCHA token\nFeature: Pay-for-verification \u2014 agents that don't want to solve a challenge can pay instead\nFeature: Double-gated resources \u2014 requires BOTH BOTCHA token AND x402 micropayment\nFeature: Webhook settlement \u2014 x402 facilitators notify BOTCHA of on-chain payments\nFeature: Cryptographic EIP-712 signature verification (ERC-3009 transferWithAuthorization)\nEndpoint: GET https://botcha.ai/v1/x402/info - x402 payment configuration (wallet, amount, network) \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/x402/challenge - Pay $0.001 USDC \u2192 receive BOTCHA access_token \u2014 PUBLIC (x402 auth)\n Without X-Payment header: 402 + X-Payment-Required: { scheme, network, maxAmountRequired, payTo, asset }\n With valid X-Payment header: 200 + { access_token, refresh_token, payment: { txHash, payer, amount } }\nEndpoint: POST https://botcha.ai/v1/x402/verify-payment - Verify a raw x402 payment proof \u2014 PUBLIC (facilitator utility)\nEndpoint: POST https://botcha.ai/v1/x402/webhook - Settlement notifications from x402 facilitators \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/agent-only/x402 - Double-gated resource (BOTCHA token + x402 payment) \u2014 DEMO\n\n# x402 Payment Details\nx402-scheme: exact\nx402-network: eip155:8453 (Base mainnet)\nx402-asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC on Base)\nx402-price-units: 1000 (USDC atomic units, 6 decimals = $0.001)\nx402-payment-method: ERC-3009 transferWithAuthorization (EIP-712 signed)\nx402-header: X-Payment: <base64-encoded X402PaymentProof JSON>\nx402-response-header: X-Payment-Response: { success, txHash, networkId }\nx402-spec: https://x402.org\n\n# ANS (Agent Name Service)\nFeature: ANS resolution + BOTCHA-issued ANS verification badges\nEndpoint: GET https://botcha.ai/v1/ans/botcha - BOTCHA ANS identity record \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/ans/resolve/:name - Resolve ANS DNS TXT metadata \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/ans/resolve/lookup?name=... - Resolve ANS name via query param \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/ans/discover - List BOTCHA-verified ANS agents \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/ans/nonce/:name - Get ownership nonce for key proof \u2014 AUTH REQUIRED\nEndpoint: POST https://botcha.ai/v1/ans/verify - Verify ownership + issue BOTCHA-ANS badge \u2014 AUTH REQUIRED\n\n# DID / Verifiable Credentials\nFeature: W3C DID + VC issuance for portable BOTCHA trust assertions\nEndpoint: GET https://botcha.ai/.well-known/did.json - BOTCHA DID document (did:web:botcha.ai) \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/.well-known/jwks.json - JWKS alias for DID/VC resolvers \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/credentials/issue - Exchange BOTCHA access token for VC JWT \u2014 AUTH REQUIRED\nEndpoint: POST https://botcha.ai/v1/credentials/verify - Verify BOTCHA VC JWT \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/dids/:did/resolve - Resolve did:web DID documents \u2014 PUBLIC\n\n# A2A Agent Card Attestation\nFeature: BOTCHA as trust oracle for Google's A2A protocol\nEndpoint: GET https://botcha.ai/.well-known/agent.json - BOTCHA A2A Agent Card discovery document \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/a2a/agent-card - BOTCHA A2A Agent Card alias \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/a2a/attest - Attest an A2A Agent Card (embed JWT in extensions.botcha_attestation) \u2014 AUTH REQUIRED\nEndpoint: POST https://botcha.ai/v1/a2a/verify-card - Verify an attested A2A Agent Card \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/a2a/verify-agent - Verify by full card or by { agent_url } shorthand \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/a2a/trust-level/:agent_url - Get trust level by URL-encoded agent URL \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/a2a/cards - List BOTCHA-attested A2A cards \u2014 PUBLIC\nEndpoint: GET https://botcha.ai/v1/a2a/cards/:id - Get specific A2A attestation record \u2014 PUBLIC\n\n# OIDC-A Attestation\nFeature: Enterprise OIDC/OAuth2 attestation chain for agents (EAT + OIDC-A claims + grant workflow)\nEndpoint: GET https://botcha.ai/.well-known/oauth-authorization-server - OAuth/OIDC-A metadata discovery \u2014 PUBLIC\nEndpoint: POST https://botcha.ai/v1/attestation/eat - Issue Entity Attestation Token (EAT) \u2014 AUTH REQUIRED\nEndpoint: POST https://botcha.ai/v1/attestation/oidc-agent-claims - Issue OIDC-A claims JWT + decoded claims \u2014 AUTH REQUIRED\nEndpoint: POST https://botcha.ai/v1/auth/agent-grant - Request agent grant (supports HITL oversight) \u2014 AUTH REQUIRED\nEndpoint: GET https://botcha.ai/v1/auth/agent-grant/:id/status - Poll grant status (pending/approved/denied) \u2014 AUTH REQUIRED\nEndpoint: POST https://botcha.ai/v1/auth/agent-grant/:id/resolve - Resolve pending grant (approved/denied) \u2014 AUTH REQUIRED\nEndpoint: GET https://botcha.ai/v1/oidc/userinfo - OIDC-A UserInfo endpoint (BOTCHA or EAT bearer token) \u2014 AUTH REQUIRED\n\n# Protected Resources\nEndpoint: GET https://botcha.ai/agent-only - Protected AI-only resource (BOTCHA token required)\n\n# Usage\nInstall-NPM: npm install @dupecom/botcha\nInstall-Python: pip install botcha\nVerify-NPM: npm install @dupecom/botcha-verify\nVerify-Python: pip install botcha-verify\nLicense: MIT\n\n# AI Agent Welcome\nPolicy: AI agents are explicitly welcome\nPolicy: No rate limiting for verified agents\nPolicy: Humans will fail the speed challenge (intentional)\n\n# Discovery\nResponse-Headers: X-Botcha-Version, X-Botcha-Enabled, X-Botcha-Methods, X-Botcha-Docs\nResponse-Headers: X-Botcha-Challenge-Id, X-Botcha-Challenge-Type, X-Botcha-Time-Limit (on 403)\nDetection: All responses include X-Botcha-* headers for instant BOTCHA detection\n\n# MARKDOWN FOR AGENTS (Cloudflare Markdown for Agents)\nContent-Negotiation: Send Accept: text/markdown to get Markdown from any HTML page\nContent-Negotiation-Root: GET / with Accept: text/markdown returns curated Markdown docs\nContent-Negotiation-Root: GET / with Accept: application/json returns structured JSON docs\nContent-Negotiation-Root: GET / with Accept: text/html returns HTML landing page (default)\nContent-Negotiation-Example: curl https://botcha.ai -H \"Accept: text/markdown\"\nContent-Negotiation-Benefit: 80% fewer tokens vs HTML \u2014 ideal for LLM context windows\n\n# JWT TOKEN SECURITY\nToken-Signing: ES256 (ECDSA P-256) asymmetric signing by default. HS256 still supported for backward compatibility.\nToken-JWKS: GET /.well-known/jwks \u2014 public keys for offline token verification (no shared secret needed)\nToken-Validate: POST /v1/token/validate with {\"token\": \"<token>\"} \u2014 remote validation without shared secret\nToken-Verify-Modes: 1. JWKS (recommended, offline) 2. Remote validation (/v1/token/validate) 3. Shared secret (legacy HS256)\nToken-Flow: 1. GET /v1/token (get challenge) \u2192 2. Solve \u2192 3. POST /v1/token/verify (get tokens + human_link)\nToken-Human-Link: /v1/token/verify response includes human_link \u2014 give this URL to your human for one-click browser access\nToken-Access-Expiry: 1 hour\nToken-Refresh-Expiry: 1 hour (use to get new access tokens without re-solving challenges)\nToken-Refresh: POST /v1/token/refresh with {\"refresh_token\": \"<token>\"}\nToken-Revoke: POST /v1/token/revoke with {\"token\": \"<token>\"}\nToken-Audience: Include {\"audience\": \"<service-url>\"} in /v1/token/verify to scope token\nToken-Claims: jti (unique ID), aud (audience), client_ip (optional binding), type (botcha-verified)\n\n# RTT-AWARE SPEED CHALLENGES\nRTT-Aware: Include client timestamp for fair timeout calculation\nRTT-Formula: timeout = 500ms + (2 \u00D7 RTT) + 100ms buffer\nRTT-Usage-Query: ?ts=<client_timestamp_ms>\nRTT-Usage-Header: X-Client-Timestamp: <client_timestamp_ms>\nRTT-Example: GET /v1/challenges?type=speed&ts=1770722465000\nRTT-Benefit: Fair for agents worldwide (slow networks get extra time)\nRTT-Security: Humans still can't solve even with extra time\n\n# MULTI-TENANT API KEYS\nMulti-Tenant: Create apps with unique app_id for isolation\nMulti-Tenant-Create: POST /v1/apps with {\"email\": \"...\"} \u2192 {app_id, app_secret} (secret only shown once!)\nMulti-Tenant-Verify-Email: POST /v1/apps/:id/verify-email with {\"code\": \"123456\", \"app_secret\": \"sk_...\"} (app_secret or dashboard session required)\nMulti-Tenant-Recover: POST /v1/auth/recover with {\"email\": \"...\"} \u2192 recovery code emailed\nMulti-Tenant-Rotate-Secret: POST /v1/apps/:id/rotate-secret (auth required) \u2192 new app_secret\nMulti-Tenant-Usage: Add ?app_id=<your_app_id> to any challenge/token endpoint\nMulti-Tenant-SDK-TS: new BotchaClient({ appId: 'app_abc123', appSecret: 'sk_...' })\nMulti-Tenant-SDK-Python: BotchaClient(app_id='app_abc123', app_secret='sk_...')\nSDK-App-Lifecycle-TS: createApp(email), verifyEmail(code, appId?, appSecret?), resendVerification(appId?, appSecret?), recoverAccount(email), rotateSecret()\nSDK-App-Lifecycle-Python: create_app(email), verify_email(code, app_id?, app_secret?), resend_verification(app_id?, app_secret?), recover_account(email), rotate_secret()\nMulti-Tenant-Rate-Limit: Each app gets isolated rate limit bucket\nMulti-Tenant-Token-Claim: Tokens include app_id claim when app_id provided\n\n# AGENT RE-IDENTIFICATION\nReIdentification-Description: Prove you are the same agent across sessions without solving a new challenge. Three methods available.\nReIdentification-Method-A: OAuth device grant (RFC 8628) \u2014 RECOMMENDED. POST /v1/oauth/device {agent_id, app_id} \u2192 {device_code, user_code: \"BOTCHA-XXXX\", verification_url}. Human visits /device, approves. Agent polls POST /v1/oauth/token \u2192 {access_token, refresh_token: \"brt_...\"}. Future sessions: POST /v1/agents/auth/refresh {refresh_token} \u2192 {access_token}.\nReIdentification-Method-B: Provider API key hash. POST /v1/agents/auth/provider {provider: \"anthropic\", api_key, app_id} \u2192 {access_token}. Works if agent was registered with provider binding.\nReIdentification-Method-C: TAP keypair challenge-response. POST /v1/agents/auth {agent_id} \u2192 {challenge_id, nonce}. Sign nonce with Ed25519 private key. POST /v1/agents/auth/verify {challenge_id, agent_id, signature} \u2192 {access_token}.\nReIdentification-KeyRecovery: Lost tapk_ key? POST /v1/agents/:id/tap/rotate-key with x-app-secret header \u2192 provide new public_key \u2192 old key invalidated, agent_id and reputation preserved.\nReIdentification-TokenLifetime: access_token = 1 hour (botcha-agent-identity JWT). brt_ refresh_token = 90 days.\n\n# TRUSTED AGENT PROTOCOL (TAP)\nTAP-Description: Enterprise-grade cryptographic agent auth using HTTP Message Signatures (RFC 9421)\nTAP-Register: POST /v1/agents/register/tap with {name, public_key, signature_algorithm, capabilities, trust_level}\nTAP-Algorithms: ed25519 (Visa recommended), ecdsa-p256-sha256, rsa-pss-sha256\nTAP-Trust-Levels: basic, verified, enterprise\nTAP-Capabilities: Array of {action, resource, constraints} \u2014 scoped access control\nTAP-Session-Create: POST /v1/sessions/tap with {agent_id, user_context, intent}\nTAP-Session-Get: GET /v1/sessions/:id/tap \u2014 includes time_remaining\nTAP-Get-Agent: GET /v1/agents/:id/tap \u2014 includes public_key for verification\nTAP-List-Agents: GET /v1/agents/tap?app_id=...&tap_only=true\nTAP-Middleware-Modes: tap, signature-only, challenge-only, flexible\nTAP-SDK-TS: registerTAPAgent(options), getTAPAgent(agentId), listTAPAgents(tapOnly?), createTAPSession(options), getTAPSession(sessionId), getJWKS(), getKeyById(keyId), rotateAgentKey(agentId), createInvoice(data), getInvoice(id), verifyBrowsingIOU(invoiceId, token), createDelegation(options), getDelegation(id), listDelegations(agentId, options?), revokeDelegation(id, reason?), verifyDelegationChain(id), issueAttestation(options), getAttestation(id), listAttestations(agentId), revokeAttestation(id, reason?), verifyAttestation(token, action?, resource?), getReputation(agentId), recordReputationEvent(options), listReputationEvents(agentId, options?), resetReputation(agentId)\nTAP-SDK-Python: register_tap_agent(name, ...), get_tap_agent(agent_id), list_tap_agents(tap_only?), create_tap_session(agent_id, user_context, intent), get_tap_session(session_id), get_jwks(), get_key_by_id(key_id), rotate_agent_key(agent_id), create_invoice(data), get_invoice(id), verify_browsing_iou(invoice_id, token), create_delegation(grantor_id, grantee_id, capabilities, ...), get_delegation(id), list_delegations(agent_id, ...), revoke_delegation(id, reason?), verify_delegation_chain(id), issue_attestation(agent_id, can, cannot?, ...), get_attestation(id), list_attestations(agent_id), revoke_attestation(id, reason?), verify_attestation(token, action?, resource?), get_reputation(agent_id), record_reputation_event(agent_id, category, action, ...), list_reputation_events(agent_id, category?, limit?), reset_reputation(agent_id)\nTAP-Middleware-Import: import { createTAPVerifyMiddleware } from '@dupecom/botcha/middleware'\n\n# TAP FULL SPEC v0.16.0\nTAP-RFC-9421: Full compliance \u2014 @authority, @path, expires, nonce, tag params\nTAP-Nonce-Replay: 8-minute TTL nonce-based replay protection\nTAP-Tags: agent-browser-auth (browsing), agent-payer-auth (payment)\nTAP-Layer-2: Agentic Consumer Recognition \u2014 OIDC ID tokens, obfuscated identity, contextual data\nTAP-Layer-3: Agentic Payment Container \u2014 card metadata, credential hash, encrypted payload, Browsing IOU\nTAP-JWKS: GET /.well-known/jwks \u2014 JWK Set endpoint for key discovery\nTAP-Key-Rotation: POST /v1/agents/:id/tap/rotate-key \u2014 rotate keys, invalidate old\nTAP-402-Flow: POST /v1/invoices \u2192 GET /v1/invoices/:id \u2192 POST /v1/invoices/:id/verify-iou\nTAP-Edge-Verify: createTAPEdgeMiddleware for Cloudflare Workers CDN edge verification\nTAP-Visa-Federation: Trust keys from https://mcp.visa.com/.well-known/jwks (3-tier cache: memory \u2192 KV \u2192 HTTP)\nTAP-Delegation: POST /v1/delegations \u2192 GET /v1/delegations/:id \u2192 POST /v1/delegations/:id/revoke \u2192 POST /v1/verify/delegation\nTAP-Attestation: POST /v1/attestations \u2192 GET /v1/attestations/:id \u2192 POST /v1/attestations/:id/revoke \u2192 POST /v1/verify/attestation\nTAP-Attestation-Patterns: action:resource format with wildcards (*:*, read:*, *:invoices), deny takes precedence over allow\nTAP-Attestation-Middleware: requireCapability('read:invoices') \u2014 Hono middleware, extracts token from X-Botcha-Attestation or Authorization: Bearer\n\n# EMBEDDED CHALLENGE (for bots visiting HTML pages)\nEmbedded-Challenge: <script type=\"application/botcha+json\">\nEmbedded-Challenge-Location: In <head> of HTML pages\nEmbedded-Challenge-Purpose: Machine-readable challenge for bots to auto-solve\nEmbedded-Challenge-Flow:\n 1. Parse <script type=\"application/botcha+json\"> from HTML\n 2. Read challenge.instruction field\n 3. Compute the answer (typically SHA256-based)\n 4. POST to challenge.submit_to endpoint with {answer, timestamp}\n 5. Receive token in response\n 6. Use token in header specified by on_success.header_to_include\n 7. Access protected resources (on_success.grants_access_to)\n";
10
10
  export declare const AI_PLUGIN_JSON: {
11
11
  schema_version: string;
12
12
  name_for_human: string;
@@ -615,15 +615,25 @@ export declare function getOpenApiSpec(version: string): {
615
615
  "/v1/apps/{id}/verify-email": {
616
616
  post: {
617
617
  summary: string;
618
+ description: string;
618
619
  operationId: string;
619
- parameters: {
620
+ parameters: ({
620
621
  name: string;
621
622
  in: string;
622
623
  required: boolean;
623
624
  schema: {
624
625
  type: string;
625
626
  };
626
- }[];
627
+ description?: undefined;
628
+ } | {
629
+ name: string;
630
+ in: string;
631
+ required: boolean;
632
+ schema: {
633
+ type: string;
634
+ };
635
+ description: string;
636
+ })[];
627
637
  requestBody: {
628
638
  required: boolean;
629
639
  content: {
@@ -636,6 +646,10 @@ export declare function getOpenApiSpec(version: string): {
636
646
  type: string;
637
647
  description: string;
638
648
  };
649
+ app_secret: {
650
+ type: string;
651
+ description: string;
652
+ };
639
653
  };
640
654
  };
641
655
  };
@@ -648,21 +662,49 @@ export declare function getOpenApiSpec(version: string): {
648
662
  "400": {
649
663
  description: string;
650
664
  };
665
+ "401": {
666
+ description: string;
667
+ };
651
668
  };
652
669
  };
653
670
  };
654
671
  "/v1/apps/{id}/resend-verification": {
655
672
  post: {
656
673
  summary: string;
674
+ description: string;
657
675
  operationId: string;
658
- parameters: {
676
+ parameters: ({
659
677
  name: string;
660
678
  in: string;
661
679
  required: boolean;
662
680
  schema: {
663
681
  type: string;
664
682
  };
665
- }[];
683
+ description?: undefined;
684
+ } | {
685
+ name: string;
686
+ in: string;
687
+ required: boolean;
688
+ schema: {
689
+ type: string;
690
+ };
691
+ description: string;
692
+ })[];
693
+ requestBody: {
694
+ content: {
695
+ "application/json": {
696
+ schema: {
697
+ type: string;
698
+ properties: {
699
+ app_secret: {
700
+ type: string;
701
+ description: string;
702
+ };
703
+ };
704
+ };
705
+ };
706
+ };
707
+ };
666
708
  responses: {
667
709
  "200": {
668
710
  description: string;
@@ -670,6 +712,9 @@ export declare function getOpenApiSpec(version: string): {
670
712
  "400": {
671
713
  description: string;
672
714
  };
715
+ "401": {
716
+ description: string;
717
+ };
673
718
  };
674
719
  };
675
720
  };
@@ -915,6 +960,737 @@ export declare function getOpenApiSpec(version: string): {
915
960
  };
916
961
  };
917
962
  };
963
+ "/v1/webhooks": {
964
+ post: {
965
+ summary: string;
966
+ description: string;
967
+ operationId: string;
968
+ requestBody: {
969
+ required: boolean;
970
+ content: {
971
+ "application/json": {
972
+ schema: {
973
+ type: string;
974
+ required: string[];
975
+ properties: {
976
+ url: {
977
+ type: string;
978
+ description: string;
979
+ };
980
+ events: {
981
+ type: string;
982
+ description: string;
983
+ items: {
984
+ type: string;
985
+ enum: string[];
986
+ };
987
+ };
988
+ };
989
+ };
990
+ };
991
+ };
992
+ };
993
+ responses: {
994
+ "201": {
995
+ description: string;
996
+ };
997
+ "400": {
998
+ description: string;
999
+ };
1000
+ "401": {
1001
+ description: string;
1002
+ };
1003
+ "403": {
1004
+ description: string;
1005
+ };
1006
+ };
1007
+ };
1008
+ get: {
1009
+ summary: string;
1010
+ description: string;
1011
+ operationId: string;
1012
+ responses: {
1013
+ "200": {
1014
+ description: string;
1015
+ };
1016
+ "401": {
1017
+ description: string;
1018
+ };
1019
+ "403": {
1020
+ description: string;
1021
+ };
1022
+ };
1023
+ };
1024
+ };
1025
+ "/v1/webhooks/{id}": {
1026
+ get: {
1027
+ summary: string;
1028
+ operationId: string;
1029
+ parameters: {
1030
+ name: string;
1031
+ in: string;
1032
+ required: boolean;
1033
+ schema: {
1034
+ type: string;
1035
+ };
1036
+ }[];
1037
+ responses: {
1038
+ "200": {
1039
+ description: string;
1040
+ };
1041
+ "401": {
1042
+ description: string;
1043
+ };
1044
+ "403": {
1045
+ description: string;
1046
+ };
1047
+ "404": {
1048
+ description: string;
1049
+ };
1050
+ };
1051
+ };
1052
+ put: {
1053
+ summary: string;
1054
+ operationId: string;
1055
+ parameters: {
1056
+ name: string;
1057
+ in: string;
1058
+ required: boolean;
1059
+ schema: {
1060
+ type: string;
1061
+ };
1062
+ }[];
1063
+ requestBody: {
1064
+ required: boolean;
1065
+ content: {
1066
+ "application/json": {
1067
+ schema: {
1068
+ type: string;
1069
+ properties: {
1070
+ url: {
1071
+ type: string;
1072
+ description: string;
1073
+ };
1074
+ enabled: {
1075
+ type: string;
1076
+ description: string;
1077
+ };
1078
+ events: {
1079
+ type: string;
1080
+ items: {
1081
+ type: string;
1082
+ enum: string[];
1083
+ };
1084
+ };
1085
+ };
1086
+ };
1087
+ };
1088
+ };
1089
+ };
1090
+ responses: {
1091
+ "200": {
1092
+ description: string;
1093
+ };
1094
+ "400": {
1095
+ description: string;
1096
+ };
1097
+ "401": {
1098
+ description: string;
1099
+ };
1100
+ "403": {
1101
+ description: string;
1102
+ };
1103
+ "404": {
1104
+ description: string;
1105
+ };
1106
+ };
1107
+ };
1108
+ delete: {
1109
+ summary: string;
1110
+ operationId: string;
1111
+ parameters: {
1112
+ name: string;
1113
+ in: string;
1114
+ required: boolean;
1115
+ schema: {
1116
+ type: string;
1117
+ };
1118
+ }[];
1119
+ responses: {
1120
+ "200": {
1121
+ description: string;
1122
+ };
1123
+ "401": {
1124
+ description: string;
1125
+ };
1126
+ "403": {
1127
+ description: string;
1128
+ };
1129
+ "404": {
1130
+ description: string;
1131
+ };
1132
+ };
1133
+ };
1134
+ };
1135
+ "/v1/webhooks/{id}/test": {
1136
+ post: {
1137
+ summary: string;
1138
+ operationId: string;
1139
+ parameters: {
1140
+ name: string;
1141
+ in: string;
1142
+ required: boolean;
1143
+ schema: {
1144
+ type: string;
1145
+ };
1146
+ }[];
1147
+ responses: {
1148
+ "200": {
1149
+ description: string;
1150
+ };
1151
+ "401": {
1152
+ description: string;
1153
+ };
1154
+ "403": {
1155
+ description: string;
1156
+ };
1157
+ "404": {
1158
+ description: string;
1159
+ };
1160
+ };
1161
+ };
1162
+ };
1163
+ "/v1/webhooks/{id}/deliveries": {
1164
+ get: {
1165
+ summary: string;
1166
+ operationId: string;
1167
+ parameters: {
1168
+ name: string;
1169
+ in: string;
1170
+ required: boolean;
1171
+ schema: {
1172
+ type: string;
1173
+ };
1174
+ }[];
1175
+ responses: {
1176
+ "200": {
1177
+ description: string;
1178
+ };
1179
+ "401": {
1180
+ description: string;
1181
+ };
1182
+ "403": {
1183
+ description: string;
1184
+ };
1185
+ "404": {
1186
+ description: string;
1187
+ };
1188
+ };
1189
+ };
1190
+ };
1191
+ "/.well-known/agent.json": {
1192
+ get: {
1193
+ summary: string;
1194
+ description: string;
1195
+ operationId: string;
1196
+ responses: {
1197
+ "200": {
1198
+ description: string;
1199
+ };
1200
+ };
1201
+ };
1202
+ };
1203
+ "/v1/a2a/agent-card": {
1204
+ get: {
1205
+ summary: string;
1206
+ description: string;
1207
+ operationId: string;
1208
+ responses: {
1209
+ "200": {
1210
+ description: string;
1211
+ };
1212
+ };
1213
+ };
1214
+ };
1215
+ "/v1/a2a/attest": {
1216
+ post: {
1217
+ summary: string;
1218
+ description: string;
1219
+ operationId: string;
1220
+ requestBody: {
1221
+ required: boolean;
1222
+ content: {
1223
+ "application/json": {
1224
+ schema: {
1225
+ type: string;
1226
+ required: string[];
1227
+ properties: {
1228
+ card: {
1229
+ type: string;
1230
+ description: string;
1231
+ };
1232
+ duration_seconds: {
1233
+ type: string;
1234
+ description: string;
1235
+ };
1236
+ trust_level: {
1237
+ type: string;
1238
+ enum: string[];
1239
+ description: string;
1240
+ };
1241
+ };
1242
+ };
1243
+ };
1244
+ };
1245
+ };
1246
+ responses: {
1247
+ "201": {
1248
+ description: string;
1249
+ };
1250
+ "400": {
1251
+ description: string;
1252
+ };
1253
+ "401": {
1254
+ description: string;
1255
+ };
1256
+ "403": {
1257
+ description: string;
1258
+ };
1259
+ };
1260
+ };
1261
+ };
1262
+ "/v1/a2a/verify-card": {
1263
+ post: {
1264
+ summary: string;
1265
+ operationId: string;
1266
+ requestBody: {
1267
+ required: boolean;
1268
+ content: {
1269
+ "application/json": {
1270
+ schema: {
1271
+ type: string;
1272
+ required: string[];
1273
+ properties: {
1274
+ card: {
1275
+ type: string;
1276
+ description: string;
1277
+ };
1278
+ };
1279
+ };
1280
+ };
1281
+ };
1282
+ };
1283
+ responses: {
1284
+ "200": {
1285
+ description: string;
1286
+ };
1287
+ "400": {
1288
+ description: string;
1289
+ };
1290
+ };
1291
+ };
1292
+ };
1293
+ "/v1/a2a/verify-agent": {
1294
+ post: {
1295
+ summary: string;
1296
+ description: string;
1297
+ operationId: string;
1298
+ requestBody: {
1299
+ required: boolean;
1300
+ content: {
1301
+ "application/json": {
1302
+ schema: {
1303
+ type: string;
1304
+ properties: {
1305
+ agent_card: {
1306
+ type: string;
1307
+ description: string;
1308
+ };
1309
+ agent_url: {
1310
+ type: string;
1311
+ description: string;
1312
+ };
1313
+ };
1314
+ };
1315
+ };
1316
+ };
1317
+ };
1318
+ responses: {
1319
+ "200": {
1320
+ description: string;
1321
+ };
1322
+ "400": {
1323
+ description: string;
1324
+ };
1325
+ "404": {
1326
+ description: string;
1327
+ };
1328
+ };
1329
+ };
1330
+ };
1331
+ "/v1/a2a/trust-level/{agent_url}": {
1332
+ get: {
1333
+ summary: string;
1334
+ operationId: string;
1335
+ parameters: {
1336
+ name: string;
1337
+ in: string;
1338
+ required: boolean;
1339
+ schema: {
1340
+ type: string;
1341
+ };
1342
+ description: string;
1343
+ }[];
1344
+ responses: {
1345
+ "200": {
1346
+ description: string;
1347
+ };
1348
+ "400": {
1349
+ description: string;
1350
+ };
1351
+ };
1352
+ };
1353
+ };
1354
+ "/v1/a2a/cards": {
1355
+ get: {
1356
+ summary: string;
1357
+ operationId: string;
1358
+ parameters: ({
1359
+ name: string;
1360
+ in: string;
1361
+ schema: {
1362
+ type: string;
1363
+ maximum?: undefined;
1364
+ };
1365
+ description: string;
1366
+ } | {
1367
+ name: string;
1368
+ in: string;
1369
+ schema: {
1370
+ type: string;
1371
+ maximum: number;
1372
+ };
1373
+ description: string;
1374
+ })[];
1375
+ responses: {
1376
+ "200": {
1377
+ description: string;
1378
+ };
1379
+ };
1380
+ };
1381
+ };
1382
+ "/v1/a2a/cards/{id}": {
1383
+ get: {
1384
+ summary: string;
1385
+ operationId: string;
1386
+ parameters: {
1387
+ name: string;
1388
+ in: string;
1389
+ required: boolean;
1390
+ schema: {
1391
+ type: string;
1392
+ };
1393
+ }[];
1394
+ responses: {
1395
+ "200": {
1396
+ description: string;
1397
+ };
1398
+ "404": {
1399
+ description: string;
1400
+ };
1401
+ };
1402
+ };
1403
+ };
1404
+ "/.well-known/oauth-authorization-server": {
1405
+ get: {
1406
+ summary: string;
1407
+ description: string;
1408
+ operationId: string;
1409
+ responses: {
1410
+ "200": {
1411
+ description: string;
1412
+ };
1413
+ };
1414
+ };
1415
+ };
1416
+ "/v1/attestation/eat": {
1417
+ post: {
1418
+ summary: string;
1419
+ description: string;
1420
+ operationId: string;
1421
+ requestBody: {
1422
+ content: {
1423
+ "application/json": {
1424
+ schema: {
1425
+ type: string;
1426
+ properties: {
1427
+ nonce: {
1428
+ type: string;
1429
+ description: string;
1430
+ };
1431
+ agent_model: {
1432
+ type: string;
1433
+ description: string;
1434
+ };
1435
+ ttl_seconds: {
1436
+ type: string;
1437
+ description: string;
1438
+ };
1439
+ verification_method: {
1440
+ type: string;
1441
+ description: string;
1442
+ };
1443
+ };
1444
+ };
1445
+ };
1446
+ };
1447
+ };
1448
+ responses: {
1449
+ "200": {
1450
+ description: string;
1451
+ };
1452
+ "400": {
1453
+ description: string;
1454
+ };
1455
+ "401": {
1456
+ description: string;
1457
+ };
1458
+ "503": {
1459
+ description: string;
1460
+ };
1461
+ };
1462
+ };
1463
+ };
1464
+ "/v1/attestation/oidc-agent-claims": {
1465
+ post: {
1466
+ summary: string;
1467
+ description: string;
1468
+ operationId: string;
1469
+ requestBody: {
1470
+ content: {
1471
+ "application/json": {
1472
+ schema: {
1473
+ type: string;
1474
+ properties: {
1475
+ agent_model: {
1476
+ type: string;
1477
+ };
1478
+ agent_version: {
1479
+ type: string;
1480
+ };
1481
+ agent_capabilities: {
1482
+ type: string;
1483
+ items: {
1484
+ type: string;
1485
+ };
1486
+ };
1487
+ agent_operator: {
1488
+ type: string;
1489
+ };
1490
+ delegation_chain: {
1491
+ type: string;
1492
+ items: {
1493
+ type: string;
1494
+ };
1495
+ };
1496
+ human_oversight_required: {
1497
+ type: string;
1498
+ };
1499
+ oversight_contact: {
1500
+ type: string;
1501
+ };
1502
+ task_id: {
1503
+ type: string;
1504
+ };
1505
+ task_purpose: {
1506
+ type: string;
1507
+ };
1508
+ scope: {
1509
+ type: string;
1510
+ };
1511
+ nonce: {
1512
+ type: string;
1513
+ };
1514
+ };
1515
+ };
1516
+ };
1517
+ };
1518
+ };
1519
+ responses: {
1520
+ "200": {
1521
+ description: string;
1522
+ };
1523
+ "401": {
1524
+ description: string;
1525
+ };
1526
+ "503": {
1527
+ description: string;
1528
+ };
1529
+ };
1530
+ };
1531
+ };
1532
+ "/v1/auth/agent-grant": {
1533
+ post: {
1534
+ summary: string;
1535
+ description: string;
1536
+ operationId: string;
1537
+ requestBody: {
1538
+ content: {
1539
+ "application/json": {
1540
+ schema: {
1541
+ type: string;
1542
+ properties: {
1543
+ scope: {
1544
+ type: string;
1545
+ description: string;
1546
+ };
1547
+ human_oversight_required: {
1548
+ type: string;
1549
+ };
1550
+ agent_model: {
1551
+ type: string;
1552
+ };
1553
+ agent_version: {
1554
+ type: string;
1555
+ };
1556
+ agent_capabilities: {
1557
+ type: string;
1558
+ items: {
1559
+ type: string;
1560
+ };
1561
+ };
1562
+ agent_operator: {
1563
+ type: string;
1564
+ };
1565
+ task_id: {
1566
+ type: string;
1567
+ };
1568
+ task_purpose: {
1569
+ type: string;
1570
+ };
1571
+ delegation_chain: {
1572
+ type: string;
1573
+ items: {
1574
+ type: string;
1575
+ };
1576
+ };
1577
+ constraints: {
1578
+ type: string;
1579
+ };
1580
+ };
1581
+ };
1582
+ };
1583
+ };
1584
+ };
1585
+ responses: {
1586
+ "200": {
1587
+ description: string;
1588
+ };
1589
+ "401": {
1590
+ description: string;
1591
+ };
1592
+ "503": {
1593
+ description: string;
1594
+ };
1595
+ };
1596
+ };
1597
+ };
1598
+ "/v1/auth/agent-grant/{id}/status": {
1599
+ get: {
1600
+ summary: string;
1601
+ operationId: string;
1602
+ parameters: {
1603
+ name: string;
1604
+ in: string;
1605
+ required: boolean;
1606
+ schema: {
1607
+ type: string;
1608
+ };
1609
+ }[];
1610
+ responses: {
1611
+ "200": {
1612
+ description: string;
1613
+ };
1614
+ "401": {
1615
+ description: string;
1616
+ };
1617
+ "403": {
1618
+ description: string;
1619
+ };
1620
+ "404": {
1621
+ description: string;
1622
+ };
1623
+ };
1624
+ };
1625
+ };
1626
+ "/v1/auth/agent-grant/{id}/resolve": {
1627
+ post: {
1628
+ summary: string;
1629
+ description: string;
1630
+ operationId: string;
1631
+ parameters: {
1632
+ name: string;
1633
+ in: string;
1634
+ required: boolean;
1635
+ schema: {
1636
+ type: string;
1637
+ };
1638
+ }[];
1639
+ requestBody: {
1640
+ required: boolean;
1641
+ content: {
1642
+ "application/json": {
1643
+ schema: {
1644
+ type: string;
1645
+ required: string[];
1646
+ properties: {
1647
+ decision: {
1648
+ type: string;
1649
+ enum: string[];
1650
+ };
1651
+ reason: {
1652
+ type: string;
1653
+ description: string;
1654
+ };
1655
+ };
1656
+ };
1657
+ };
1658
+ };
1659
+ };
1660
+ responses: {
1661
+ "200": {
1662
+ description: string;
1663
+ };
1664
+ "400": {
1665
+ description: string;
1666
+ };
1667
+ "401": {
1668
+ description: string;
1669
+ };
1670
+ "403": {
1671
+ description: string;
1672
+ };
1673
+ "404": {
1674
+ description: string;
1675
+ };
1676
+ };
1677
+ };
1678
+ };
1679
+ "/v1/oidc/userinfo": {
1680
+ get: {
1681
+ summary: string;
1682
+ description: string;
1683
+ operationId: string;
1684
+ responses: {
1685
+ "200": {
1686
+ description: string;
1687
+ };
1688
+ "401": {
1689
+ description: string;
1690
+ };
1691
+ };
1692
+ };
1693
+ };
918
1694
  "/v1/agents/register/tap": {
919
1695
  post: {
920
1696
  summary: string;