@dupecom/botcha-cloudflare 0.21.0 → 0.23.0

package/dist/static.js

@@ -86,6 +86,26 @@ curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 | \`GET\` | \`/v1/agents/:id\` | Get agent by ID (public, no auth) |
 | \`GET\` | \`/v1/agents\` | List all agents for your app (auth required) |
 
+### Webhooks (v0.22.0)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/webhooks\` | Register a webhook endpoint (returns secret once) |
+| \`GET\` | \`/v1/webhooks\` | List webhooks for your app |
+| \`GET\` | \`/v1/webhooks/:id\` | Get webhook details |
+| \`PUT\` | \`/v1/webhooks/:id\` | Update URL, event subscriptions, enabled state |
+| \`DELETE\` | \`/v1/webhooks/:id\` | Delete webhook + secret + delivery logs |
+| \`POST\` | \`/v1/webhooks/:id/test\` | Send a signed test event to endpoint |
+| \`GET\` | \`/v1/webhooks/:id/deliveries\` | List last 100 delivery attempts |
+
+Supported emitted events:
+- \`agent.tap.registered\`
+- \`token.created\`
+- \`token.revoked\`
+- \`tap.session.created\`
+- \`delegation.created\`
+- \`delegation.revoked\`
+
 ### TAP (Trusted Agent Protocol)
 
 | Method | Path | Description |
@@ -113,6 +133,85 @@ curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 | \`GET\` | \`/v1/invoices/:id\` | Get invoice details |
 | \`POST\` | \`/v1/invoices/:id/verify-iou\` | Verify Browsing IOU |
 
+### x402 Payment Gating (Epic 3 — v0.22.0)
+
+Pay $0.001 USDC on Base to receive a BOTCHA verification token. No challenge required.
+
+\`\`\`bash
+# 1. Discover payment requirements
+curl https://botcha.ai/v1/x402/info
+
+# 2. Request without payment → 402
+curl https://botcha.ai/v1/x402/challenge
+# Response: 402 + X-Payment-Required: {"scheme":"exact","network":"eip155:8453",...}
+
+# 3. Sign ERC-3009 transferWithAuthorization and encode as base64 JSON
+PAYMENT_PROOF="base64({ scheme: 'exact', network: 'eip155:8453', payload: { from, to, value, validAfter, validBefore, nonce, signature } })"
+
+# 4. Pay and receive token
+curl https://botcha.ai/v1/x402/challenge -H "X-Payment: $PAYMENT_PROOF"
+# Response: 200 + { access_token, refresh_token, payment: { txHash, payer, amount } }
+
+# 5. Access double-gated resource (BOTCHA + x402)
+curl https://botcha.ai/agent-only/x402 \
+  -H "Authorization: Bearer <access_token>" \
+  -H "X-Payment: $RESOURCE_PAYMENT_PROOF"
+\`\`\`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/v1/x402/info\` | Payment configuration (wallet, amount, network) — PUBLIC |
+| \`GET\` | \`/v1/x402/challenge\` | Pay → BOTCHA token (no app_id needed) — PUBLIC |
+| \`POST\` | \`/v1/x402/verify-payment\` | Verify raw x402 payment proof — PUBLIC |
+| \`POST\` | \`/v1/x402/webhook\` | Facilitator settlement webhook — PUBLIC |
+| \`GET\` | \`/agent-only/x402\` | Demo: BOTCHA token + x402 payment required |
+
+### ANS (Agent Name Service)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/v1/ans/botcha\` | BOTCHA's ANS identity record — PUBLIC |
+| \`GET\` | \`/v1/ans/resolve/:name\` | Resolve ANS name via DNS TXT — PUBLIC |
+| \`GET\` | \`/v1/ans/resolve/lookup?name=...\` | Resolve ANS name via query parameter — PUBLIC |
+| \`GET\` | \`/v1/ans/discover\` | List BOTCHA-verified ANS agents — PUBLIC |
+| \`GET\` | \`/v1/ans/nonce/:name\` | Get ANS ownership nonce — AUTH REQUIRED |
+| \`POST\` | \`/v1/ans/verify\` | Verify ANS ownership and issue badge — AUTH REQUIRED |
+
+### DID / Verifiable Credentials
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/.well-known/did.json\` | BOTCHA DID document (did:web:botcha.ai) — PUBLIC |
+| \`GET\` | \`/.well-known/jwks.json\` | JWKS alias for resolvers that append \`.json\` — PUBLIC |
+| \`POST\` | \`/v1/credentials/issue\` | Issue BOTCHA VC from access token — AUTH REQUIRED |
+| \`POST\` | \`/v1/credentials/verify\` | Verify BOTCHA VC JWT — PUBLIC |
+| \`GET\` | \`/v1/dids/:did/resolve\` | Resolve did:web DID documents — PUBLIC |
+
+### A2A Agent Card Attestation
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/.well-known/agent.json\` | BOTCHA A2A Agent Card discovery document — PUBLIC |
+| \`GET\` | \`/v1/a2a/agent-card\` | BOTCHA A2A Agent Card alias — PUBLIC |
+| \`POST\` | \`/v1/a2a/attest\` | Attest an A2A Agent Card (embeds JWT in extensions.botcha_attestation) — AUTH REQUIRED |
+| \`POST\` | \`/v1/a2a/verify-card\` | Verify an attested A2A Agent Card — PUBLIC |
+| \`POST\` | \`/v1/a2a/verify-agent\` | Verify by full card or by \`agent_url\` shorthand — PUBLIC |
+| \`GET\` | \`/v1/a2a/trust-level/:agent_url\` | Get current trust level for URL-encoded agent URL — PUBLIC |
+| \`GET\` | \`/v1/a2a/cards\` | List BOTCHA-attested A2A cards — PUBLIC |
+| \`GET\` | \`/v1/a2a/cards/:id\` | Get specific A2A attestation record — PUBLIC |
+
+### OIDC-A Attestation
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/.well-known/oauth-authorization-server\` | OAuth/OIDC-A authorization server metadata — PUBLIC |
+| \`POST\` | \`/v1/attestation/eat\` | Issue Entity Attestation Token (EAT, RFC 9334 profile) — AUTH REQUIRED |
+| \`POST\` | \`/v1/attestation/oidc-agent-claims\` | Issue OIDC-A claims block (JWT + decoded claims) — AUTH REQUIRED |
+| \`POST\` | \`/v1/auth/agent-grant\` | Create OAuth-style agent grant — AUTH REQUIRED |
+| \`GET\` | \`/v1/auth/agent-grant/:id/status\` | Poll pending grant status — AUTH REQUIRED |
+| \`POST\` | \`/v1/auth/agent-grant/:id/resolve\` | Approve/deny grant — AUTH REQUIRED |
+| \`GET\` | \`/v1/oidc/userinfo\` | OIDC-A UserInfo endpoint (accepts BOTCHA or EAT bearer token) — AUTH REQUIRED |
+
 ### TAP Full Spec — Verification (v0.16.0)
 
 | Method | Path | Description |
@@ -340,6 +439,14 @@ API: https://botcha.ai/openapi.json
 API-Type: REST
 API-Format: OpenAPI 3.1.0
 
+# MCP Server (Model Context Protocol)
+MCP: https://botcha.ai/mcp
+MCP-Discovery: https://botcha.ai/.well-known/mcp.json
+MCP-Transport: Streamable HTTP (2025-03-26 spec)
+MCP-Protocol: JSON-RPC 2.0
+MCP-Tools: list_features, get_feature, search_docs, list_endpoints, get_endpoint, get_example
+MCP-Note: Ask the BOTCHA MCP server any question about features, endpoints, or code examples
+
 # Documentation
 Docs: https://botcha.ai
 Docs: https://botcha.ai/docs
@@ -366,6 +473,9 @@ Feature: Email-Tied App Creation (email required, 6-digit verification, account
 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)
+Feature: Agent Re-identification — prove you are the same agent in a new session via OAuth refresh token (brt_), provider API key hash, or Ed25519 keypair challenge-response
+Feature: Agent OAuth Device Authorization Grant (RFC 8628) — human approves at /device, agent polls for brt_... refresh token valid 90 days
+Feature: TAP Key Recovery — rotate lost keypair using app_secret as recovery anchor
 Feature: Trusted Agent Protocol (TAP) — cryptographic agent auth with HTTP Message Signatures (RFC 9421)
 Feature: TAP Capabilities (action + resource scoping for agent sessions)
 Feature: TAP Trust Levels (basic, verified, enterprise)
@@ -421,6 +531,21 @@ Endpoint: POST https://botcha.ai/gate - Submit code form, redirects to /go/:code
 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) — requires app_id
 Endpoint: GET https://botcha.ai/v1/agents - List all agents for authenticated app — requires app_id
+Endpoint: DELETE https://botcha.ai/v1/agents/:id - Delete agent — requires dashboard session
+
+# Agent Re-identification (PUBLIC — no auth needed, proves same agent across sessions)
+Endpoint: POST https://botcha.ai/v1/agents/auth - Step 1 keypair auth: { agent_id } → { challenge_id, nonce } — PUBLIC
+Endpoint: POST https://botcha.ai/v1/agents/auth/verify - Step 2 keypair auth: { challenge_id, agent_id, signature } → { access_token } — PUBLIC
+Endpoint: POST https://botcha.ai/v1/agents/auth/provider - Provider key auth: { provider, api_key, app_id } → { access_token } — PUBLIC
+Endpoint: POST https://botcha.ai/v1/agents/auth/refresh - OAuth refresh: { refresh_token: "brt_..." } → { access_token } — PUBLIC
+
+# Agent OAuth — Device Authorization Grant (RFC 8628)
+Endpoint: POST https://botcha.ai/v1/oauth/device - Start device auth: { agent_id, app_id } → { device_code, user_code, verification_url, expires_in: 600, interval: 5 } — PUBLIC
+Endpoint: POST https://botcha.ai/v1/oauth/token - Poll for token: { device_code, grant_type } → { access_token, refresh_token: "brt_..." } — PUBLIC
+Endpoint: POST https://botcha.ai/v1/oauth/approve - Human approval: { user_code, action: "approve"|"deny" } — PUBLIC
+Endpoint: POST https://botcha.ai/v1/oauth/revoke - Revoke refresh token: { agent_id, app_id } — PUBLIC
+Endpoint: GET https://botcha.ai/v1/oauth/lookup - Agent info for approval UI: ?user_code=BOTCHA-XXXX → { agent_id, name, operator } — PUBLIC
+Endpoint: GET https://botcha.ai/device - Human-facing OAuth approval page (requires dashboard login)
 
 # TAP (Trusted Agent Protocol) Endpoints (app_id required)
 Endpoint: POST https://botcha.ai/v1/agents/register/tap - Register TAP agent with public key + capabilities — requires app_id
@@ -433,7 +558,7 @@ Endpoint: GET https://botcha.ai/v1/sessions/:id/tap - Get TAP session info — r
 Endpoint: GET https://botcha.ai/.well-known/jwks - JWK Set for app's TAP agents (Visa spec standard) — requires app_id
 Endpoint: GET https://botcha.ai/v1/keys - List keys (supports ?keyID= query for Visa compatibility) — requires app_id
 Endpoint: GET https://botcha.ai/v1/keys/:keyId - Get specific key by ID — requires app_id
-Endpoint: POST https://botcha.ai/v1/agents/:id/tap/rotate-key - Rotate agent's key pair — requires app_id
+Endpoint: 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) — requires app_id or app_secret
 
 # TAP Full Spec — 402 Micropayments (v0.16.0) (app_id required)
 Endpoint: POST https://botcha.ai/v1/invoices - Create invoice for gated content (402 flow) — requires app_id
@@ -444,6 +569,16 @@ Endpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IO
 Endpoint: POST https://botcha.ai/v1/verify/consumer - Verify Agentic Consumer object (Layer 2) — requires app_id
 Endpoint: POST https://botcha.ai/v1/verify/payment - Verify Agentic Payment Container (Layer 3) — requires app_id
 
+# Webhooks (v0.22.0) (Bearer token with app_id claim required)
+Endpoint: POST https://botcha.ai/v1/webhooks - Register webhook endpoint (returns signing secret once)
+Endpoint: GET https://botcha.ai/v1/webhooks - List webhooks for authenticated app
+Endpoint: GET https://botcha.ai/v1/webhooks/:id - Get webhook details
+Endpoint: PUT https://botcha.ai/v1/webhooks/:id - Update url/events/enabled state
+Endpoint: DELETE https://botcha.ai/v1/webhooks/:id - Delete webhook config + secret + delivery logs
+Endpoint: POST https://botcha.ai/v1/webhooks/:id/test - Send signed test event
+Endpoint: GET https://botcha.ai/v1/webhooks/:id/deliveries - List last 100 delivery attempts
+Events: agent.tap.registered, token.created, token.revoked, tap.session.created, delegation.created, delegation.revoked
+
 # TAP Delegation Chains (v0.17.0) (app_id required)
 Endpoint: POST https://botcha.ai/v1/delegations - Create delegation (grantor→grantee with capability subset) — requires app_id
 Endpoint: GET https://botcha.ai/v1/delegations/:id - Get delegation details — requires app_id
@@ -470,8 +605,71 @@ Endpoint: POST https://botcha.ai/api/challenge - Verify standard challenge
 Endpoint: GET https://botcha.ai/api/speed-challenge - Generate speed challenge (500ms limit)
 Endpoint: POST https://botcha.ai/api/speed-challenge - Verify speed challenge
 
+# x402 Payment Gating (Epic 3 — agents pay USDC, skip the challenge)
+# Payment IS the credential on these endpoints — no app_id required
+Feature: x402 HTTP Payment Required protocol — verified agents pay $0.001 USDC on Base and receive a BOTCHA token
+Feature: Pay-for-verification — agents that don't want to solve a challenge can pay instead
+Feature: Double-gated resources — requires BOTH BOTCHA token AND x402 micropayment
+Feature: Webhook settlement — x402 facilitators notify BOTCHA of on-chain payments
+Feature: Cryptographic EIP-712 signature verification (ERC-3009 transferWithAuthorization)
+Endpoint: GET https://botcha.ai/v1/x402/info - x402 payment configuration (wallet, amount, network) — PUBLIC
+Endpoint: GET https://botcha.ai/v1/x402/challenge - Pay $0.001 USDC → receive BOTCHA access_token — PUBLIC (x402 auth)
+  Without X-Payment header: 402 + X-Payment-Required: { scheme, network, maxAmountRequired, payTo, asset }
+  With valid X-Payment header: 200 + { access_token, refresh_token, payment: { txHash, payer, amount } }
+Endpoint: POST https://botcha.ai/v1/x402/verify-payment - Verify a raw x402 payment proof — PUBLIC (facilitator utility)
+Endpoint: POST https://botcha.ai/v1/x402/webhook - Settlement notifications from x402 facilitators — PUBLIC
+Endpoint: GET https://botcha.ai/agent-only/x402 - Double-gated resource (BOTCHA token + x402 payment) — DEMO
+
+# x402 Payment Details
+x402-scheme: exact
+x402-network: eip155:8453 (Base mainnet)
+x402-asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC on Base)
+x402-price-units: 1000 (USDC atomic units, 6 decimals = $0.001)
+x402-payment-method: ERC-3009 transferWithAuthorization (EIP-712 signed)
+x402-header: X-Payment: <base64-encoded X402PaymentProof JSON>
+x402-response-header: X-Payment-Response: { success, txHash, networkId }
+x402-spec: https://x402.org
+
+# ANS (Agent Name Service)
+Feature: ANS resolution + BOTCHA-issued ANS verification badges
+Endpoint: GET https://botcha.ai/v1/ans/botcha - BOTCHA ANS identity record — PUBLIC
+Endpoint: GET https://botcha.ai/v1/ans/resolve/:name - Resolve ANS DNS TXT metadata — PUBLIC
+Endpoint: GET https://botcha.ai/v1/ans/resolve/lookup?name=... - Resolve ANS name via query param — PUBLIC
+Endpoint: GET https://botcha.ai/v1/ans/discover - List BOTCHA-verified ANS agents — PUBLIC
+Endpoint: GET https://botcha.ai/v1/ans/nonce/:name - Get ownership nonce for key proof — AUTH REQUIRED
+Endpoint: POST https://botcha.ai/v1/ans/verify - Verify ownership + issue BOTCHA-ANS badge — AUTH REQUIRED
+
+# DID / Verifiable Credentials
+Feature: W3C DID + VC issuance for portable BOTCHA trust assertions
+Endpoint: GET https://botcha.ai/.well-known/did.json - BOTCHA DID document (did:web:botcha.ai) — PUBLIC
+Endpoint: GET https://botcha.ai/.well-known/jwks.json - JWKS alias for DID/VC resolvers — PUBLIC
+Endpoint: POST https://botcha.ai/v1/credentials/issue - Exchange BOTCHA access token for VC JWT — AUTH REQUIRED
+Endpoint: POST https://botcha.ai/v1/credentials/verify - Verify BOTCHA VC JWT — PUBLIC
+Endpoint: GET https://botcha.ai/v1/dids/:did/resolve - Resolve did:web DID documents — PUBLIC
+
+# A2A Agent Card Attestation
+Feature: BOTCHA as trust oracle for Google's A2A protocol
+Endpoint: GET https://botcha.ai/.well-known/agent.json - BOTCHA A2A Agent Card discovery document — PUBLIC
+Endpoint: GET https://botcha.ai/v1/a2a/agent-card - BOTCHA A2A Agent Card alias — PUBLIC
+Endpoint: POST https://botcha.ai/v1/a2a/attest - Attest an A2A Agent Card (embed JWT in extensions.botcha_attestation) — AUTH REQUIRED
+Endpoint: POST https://botcha.ai/v1/a2a/verify-card - Verify an attested A2A Agent Card — PUBLIC
+Endpoint: POST https://botcha.ai/v1/a2a/verify-agent - Verify by full card or by { agent_url } shorthand — PUBLIC
+Endpoint: GET https://botcha.ai/v1/a2a/trust-level/:agent_url - Get trust level by URL-encoded agent URL — PUBLIC
+Endpoint: GET https://botcha.ai/v1/a2a/cards - List BOTCHA-attested A2A cards — PUBLIC
+Endpoint: GET https://botcha.ai/v1/a2a/cards/:id - Get specific A2A attestation record — PUBLIC
+
+# OIDC-A Attestation
+Feature: Enterprise OIDC/OAuth2 attestation chain for agents (EAT + OIDC-A claims + grant workflow)
+Endpoint: GET https://botcha.ai/.well-known/oauth-authorization-server - OAuth/OIDC-A metadata discovery — PUBLIC
+Endpoint: POST https://botcha.ai/v1/attestation/eat - Issue Entity Attestation Token (EAT) — AUTH REQUIRED
+Endpoint: POST https://botcha.ai/v1/attestation/oidc-agent-claims - Issue OIDC-A claims JWT + decoded claims — AUTH REQUIRED
+Endpoint: POST https://botcha.ai/v1/auth/agent-grant - Request agent grant (supports HITL oversight) — AUTH REQUIRED
+Endpoint: GET https://botcha.ai/v1/auth/agent-grant/:id/status - Poll grant status (pending/approved/denied) — AUTH REQUIRED
+Endpoint: POST https://botcha.ai/v1/auth/agent-grant/:id/resolve - Resolve pending grant (approved/denied) — AUTH REQUIRED
+Endpoint: GET https://botcha.ai/v1/oidc/userinfo - OIDC-A UserInfo endpoint (BOTCHA or EAT bearer token) — AUTH REQUIRED
+
 # Protected Resources
-Endpoint: GET https://botcha.ai/agent-only - Protected AI-only resource
+Endpoint: GET https://botcha.ai/agent-only - Protected AI-only resource (BOTCHA token required)
 
 # Usage
 Install-NPM: npm install @dupecom/botcha
@@ -535,6 +733,14 @@ SDK-App-Lifecycle-Python: create_app(email), verify_email(code, app_id?, app_sec
 Multi-Tenant-Rate-Limit: Each app gets isolated rate limit bucket
 Multi-Tenant-Token-Claim: Tokens include app_id claim when app_id provided
 
+# AGENT RE-IDENTIFICATION
+ReIdentification-Description: Prove you are the same agent across sessions without solving a new challenge. Three methods available.
+ReIdentification-Method-A: OAuth device grant (RFC 8628) — RECOMMENDED. POST /v1/oauth/device {agent_id, app_id} → {device_code, user_code: "BOTCHA-XXXX", verification_url}. Human visits /device, approves. Agent polls POST /v1/oauth/token → {access_token, refresh_token: "brt_..."}. Future sessions: POST /v1/agents/auth/refresh {refresh_token} → {access_token}.
+ReIdentification-Method-B: Provider API key hash. POST /v1/agents/auth/provider {provider: "anthropic", api_key, app_id} → {access_token}. Works if agent was registered with provider binding.
+ReIdentification-Method-C: TAP keypair challenge-response. POST /v1/agents/auth {agent_id} → {challenge_id, nonce}. Sign nonce with Ed25519 private key. POST /v1/agents/auth/verify {challenge_id, agent_id, signature} → {access_token}.
+ReIdentification-KeyRecovery: Lost tapk_ key? POST /v1/agents/:id/tap/rotate-key with x-app-secret header → provide new public_key → old key invalidated, agent_id and reputation preserved.
+ReIdentification-TokenLifetime: access_token = 1 hour (botcha-agent-identity JWT). brt_ refresh_token = 90 days.
+
 # TRUSTED AGENT PROTOCOL (TAP)
 TAP-Description: Enterprise-grade cryptographic agent auth using HTTP Message Signatures (RFC 9421)
 TAP-Register: POST /v1/agents/register/tap with {name, public_key, signature_algorithm, capabilities, trust_level}
@@ -1501,6 +1707,444 @@ export function getOpenApiSpec(version) {
                     }
                 }
             },
+            "/v1/webhooks": {
+                post: {
+                    summary: "Register webhook endpoint",
+                    description: "Create a webhook for the authenticated app. Returns signing secret once at creation.",
+                    operationId: "createWebhook",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["url"],
+                                    properties: {
+                                        "url": { type: "string", description: "HTTPS destination URL" },
+                                        "events": {
+                                            type: "array",
+                                            description: "Optional event filter. Defaults to all supported events.",
+                                            items: {
+                                                type: "string",
+                                                enum: [
+                                                    "agent.tap.registered",
+                                                    "token.created",
+                                                    "token.revoked",
+                                                    "tap.session.created",
+                                                    "delegation.created",
+                                                    "delegation.revoked"
+                                                ]
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "201": { description: "Webhook created (includes one-time secret)" },
+                        "400": { description: "Invalid url/events or webhook limit reached" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Token missing app_id" }
+                    }
+                },
+                get: {
+                    summary: "List webhooks",
+                    description: "List all webhook configurations for the authenticated app.",
+                    operationId: "listWebhooks",
+                    responses: {
+                        "200": { description: "Webhook list" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Token missing app_id" }
+                    }
+                }
+            },
+            "/v1/webhooks/{id}": {
+                get: {
+                    summary: "Get webhook",
+                    operationId: "getWebhook",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "Webhook details" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden" },
+                        "404": { description: "Webhook not found" }
+                    }
+                },
+                put: {
+                    summary: "Update webhook",
+                    operationId: "updateWebhook",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "url": { type: "string", description: "Updated HTTPS destination URL" },
+                                        "enabled": { type: "boolean", description: "Enable/disable webhook delivery" },
+                                        "events": {
+                                            type: "array",
+                                            items: {
+                                                type: "string",
+                                                enum: [
+                                                    "agent.tap.registered",
+                                                    "token.created",
+                                                    "token.revoked",
+                                                    "tap.session.created",
+                                                    "delegation.created",
+                                                    "delegation.revoked"
+                                                ]
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Webhook updated" },
+                        "400": { description: "Invalid request body" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden" },
+                        "404": { description: "Webhook not found" }
+                    }
+                },
+                delete: {
+                    summary: "Delete webhook",
+                    operationId: "deleteWebhook",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "Webhook deleted" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden" },
+                        "404": { description: "Webhook not found" }
+                    }
+                }
+            },
+            "/v1/webhooks/{id}/test": {
+                post: {
+                    summary: "Send test webhook event",
+                    operationId: "testWebhook",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "Test delivery attempt response" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden" },
+                        "404": { description: "Webhook not found" }
+                    }
+                }
+            },
+            "/v1/webhooks/{id}/deliveries": {
+                get: {
+                    summary: "List webhook delivery attempts",
+                    operationId: "listWebhookDeliveries",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "Recent delivery attempts" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden" },
+                        "404": { description: "Webhook not found" }
+                    }
+                }
+            },
+            "/.well-known/agent.json": {
+                get: {
+                    summary: "BOTCHA A2A Agent Card",
+                    description: "Public A2A discovery document for BOTCHA.",
+                    operationId: "getBotchaA2ACard",
+                    responses: {
+                        "200": { description: "A2A Agent Card JSON" }
+                    }
+                }
+            },
+            "/v1/a2a/agent-card": {
+                get: {
+                    summary: "BOTCHA A2A Agent Card alias",
+                    description: "Alias for /.well-known/agent.json.",
+                    operationId: "getBotchaA2ACardAlias",
+                    responses: {
+                        "200": { description: "A2A Agent Card JSON" }
+                    }
+                }
+            },
+            "/v1/a2a/attest": {
+                post: {
+                    summary: "Attest an A2A Agent Card",
+                    description: "Issue a BOTCHA attestation and embed it in extensions.botcha_attestation.",
+                    operationId: "attestA2ACard",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["card"],
+                                    properties: {
+                                        "card": { type: "object", description: "A2A Agent Card JSON" },
+                                        "duration_seconds": { type: "integer", description: "TTL in seconds (default 86400, max 2592000)" },
+                                        "trust_level": { type: "string", enum: ["basic", "verified", "enterprise"], description: "Trust level label" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "201": { description: "Card attested successfully" },
+                        "400": { description: "Invalid card payload" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Token missing app_id" }
+                    }
+                }
+            },
+            "/v1/a2a/verify-card": {
+                post: {
+                    summary: "Verify an attested A2A Agent Card",
+                    operationId: "verifyA2ACard",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["card"],
+                                    properties: {
+                                        "card": { type: "object", description: "A2A Agent Card with extensions.botcha_attestation" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Verification result (valid true/false)" },
+                        "400": { description: "Missing card payload" }
+                    }
+                }
+            },
+            "/v1/a2a/verify-agent": {
+                post: {
+                    summary: "Verify agent by card or URL",
+                    description: "Verify by full agent_card payload or by agent_url shorthand lookup.",
+                    operationId: "verifyA2AAgent",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "agent_card": { type: "object", description: "A2A Agent Card with embedded attestation" },
+                                        "agent_url": { type: "string", description: "Agent URL shorthand for latest active attestation lookup" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Verification result" },
+                        "400": { description: "Missing agent_card or agent_url" },
+                        "404": { description: "No active attestation found for agent_url" }
+                    }
+                }
+            },
+            "/v1/a2a/trust-level/{agent_url}": {
+                get: {
+                    summary: "Get trust level for agent URL",
+                    operationId: "getA2ATrustLevel",
+                    parameters: [
+                        { name: "agent_url", in: "path", required: true, schema: { type: "string" }, description: "URL-encoded agent URL" }
+                    ],
+                    responses: {
+                        "200": { description: "Trust level result" },
+                        "400": { description: "Missing agent_url" }
+                    }
+                }
+            },
+            "/v1/a2a/cards": {
+                get: {
+                    summary: "List attested A2A cards",
+                    operationId: "listA2ACards",
+                    parameters: [
+                        { name: "verified", in: "query", schema: { type: "boolean" }, description: "Set false to include revoked records" },
+                        { name: "agent_url", in: "query", schema: { type: "string" }, description: "Filter by agent URL" },
+                        { name: "limit", in: "query", schema: { type: "integer", maximum: 200 }, description: "Max records (default 50)" }
+                    ],
+                    responses: {
+                        "200": { description: "A2A attestation registry list" }
+                    }
+                }
+            },
+            "/v1/a2a/cards/{id}": {
+                get: {
+                    summary: "Get A2A attestation by ID",
+                    operationId: "getA2ACardAttestation",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "A2A attestation record" },
+                        "404": { description: "Attestation not found or expired" }
+                    }
+                }
+            },
+            "/.well-known/oauth-authorization-server": {
+                get: {
+                    summary: "OIDC/OAuth authorization server metadata",
+                    description: "RFC 8414 authorization server metadata with OIDC-A specific endpoints.",
+                    operationId: "getOIDCAuthorizationServerMetadata",
+                    responses: {
+                        "200": { description: "Authorization server metadata" }
+                    }
+                }
+            },
+            "/v1/attestation/eat": {
+                post: {
+                    summary: "Issue Entity Attestation Token (EAT)",
+                    description: "Issue a signed EAT token from a verified BOTCHA bearer token.",
+                    operationId: "issueEAT",
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "nonce": { type: "string", description: "Optional nonce for freshness binding" },
+                                        "agent_model": { type: "string", description: "Optional agent model label" },
+                                        "ttl_seconds": { type: "integer", description: "Optional TTL in seconds (max 3600)" },
+                                        "verification_method": { type: "string", description: "Verification method label override" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "EAT token issued" },
+                        "400": { description: "Invalid request (e.g., ttl_seconds)" },
+                        "401": { description: "Unauthorized" },
+                        "503": { description: "Signing key not configured" }
+                    }
+                }
+            },
+            "/v1/attestation/oidc-agent-claims": {
+                post: {
+                    summary: "Issue OIDC-A claims block",
+                    description: "Issue OIDC-A claims JWT and decoded claims object for embedding in ID tokens.",
+                    operationId: "issueOIDCAgentClaims",
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "agent_model": { type: "string" },
+                                        "agent_version": { type: "string" },
+                                        "agent_capabilities": { type: "array", items: { type: "string" } },
+                                        "agent_operator": { type: "string" },
+                                        "delegation_chain": { type: "array", items: { type: "string" } },
+                                        "human_oversight_required": { type: "boolean" },
+                                        "oversight_contact": { type: "string" },
+                                        "task_id": { type: "string" },
+                                        "task_purpose": { type: "string" },
+                                        "scope": { type: "string" },
+                                        "nonce": { type: "string" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "OIDC-A claims issued" },
+                        "401": { description: "Unauthorized" },
+                        "503": { description: "Signing key not configured" }
+                    }
+                }
+            },
+            "/v1/auth/agent-grant": {
+                post: {
+                    summary: "Create agent authorization grant",
+                    description: "Issue an OAuth-style agent grant with optional human-in-the-loop status flow.",
+                    operationId: "createAgentGrant",
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "scope": { type: "string", description: "Space-separated requested scope string" },
+                                        "human_oversight_required": { type: "boolean" },
+                                        "agent_model": { type: "string" },
+                                        "agent_version": { type: "string" },
+                                        "agent_capabilities": { type: "array", items: { type: "string" } },
+                                        "agent_operator": { type: "string" },
+                                        "task_id": { type: "string" },
+                                        "task_purpose": { type: "string" },
+                                        "delegation_chain": { type: "array", items: { type: "string" } },
+                                        "constraints": { type: "object" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Grant issued (or pending human approval)" },
+                        "401": { description: "Unauthorized" },
+                        "503": { description: "Signing key not configured" }
+                    }
+                }
+            },
+            "/v1/auth/agent-grant/{id}/status": {
+                get: {
+                    summary: "Get agent grant status",
+                    operationId: "getAgentGrantStatus",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "Grant status payload" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden (app ownership required)" },
+                        "404": { description: "Grant not found or expired" }
+                    }
+                }
+            },
+            "/v1/auth/agent-grant/{id}/resolve": {
+                post: {
+                    summary: "Resolve pending agent grant",
+                    description: "Approve or deny a pending human-in-the-loop grant.",
+                    operationId: "resolveAgentGrant",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["decision"],
+                                    properties: {
+                                        "decision": { type: "string", enum: ["approved", "denied"] },
+                                        "reason": { type: "string", description: "Required when decision is denied" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Grant resolved" },
+                        "400": { description: "Invalid decision or missing reason" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden (app ownership required)" },
+                        "404": { description: "Grant not found or expired" }
+                    }
+                }
+            },
+            "/v1/oidc/userinfo": {
+                get: {
+                    summary: "OIDC-A UserInfo endpoint",
+                    description: "Returns OIDC-compatible UserInfo claims for BOTCHA or EAT bearer tokens.",
+                    operationId: "getOIDCUserInfo",
+                    responses: {
+                        "200": { description: "OIDC UserInfo payload" },
+                        "401": { description: "Unauthorized" }
+                    }
+                }
+            },
             "/v1/agents/register/tap": {
                 post: {
                     summary: "Register a TAP-enabled agent",