@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/static.js

@@ -35,17 +35,26 @@ curl -X POST https://botcha.ai/v1/challenges/{id}/verify -H "Content-Type: appli
 curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 \`\`\`
 
+## App Registration Required (v0.21.0)
+
+**All API endpoints require a registered app with verified email.**
+
+- Register for free: \`POST /v1/apps\` with your email
+- The homepage demo at botcha.ai lets agents try challenges without registering
+- Provide app_id via \`?app_id=\`, \`X-App-Id\` header, or JWT claim
+
 ## Onboarding
 
 1. Ask your human operator for their email address
-2. \`POST /v1/apps\` with \`{"email":"human@example.com"}\` — returns \`app_id\` + \`app_secret\` (secret shown ONCE)
+2. \`POST /v1/apps\` with \`{"email":"human@example.com","name":"My App"}\` — returns \`app_id\` + \`app_secret\` (secret shown ONCE)
 3. Human receives a 6-digit verification code via email — ask them for it
-4. \`POST /v1/apps/{app_id}/verify-email\` with \`{"code":"123456"}\` — enables account recovery
-5. Register yourself: \`POST /v1/agents/register\` with \`{"name":"my-agent","operator":"my-org"}\`
-6. Solve challenges: \`GET /v1/challenges?app_id=...\` then \`POST /v1/challenges/{id}/verify\`
-7. Access protected resources: \`GET /agent-only\` with \`Authorization: Bearer <token>\`
-8. Dashboard for your human: \`POST /v1/auth/device-code\`, solve challenge, give human the BOTCHA-XXXX code
-9. Lost your secret? \`POST /v1/auth/recover\` with \`{"email":"..."}\`
+4. \`POST /v1/apps/{app_id}/verify-email\` with \`{"code":"123456","app_secret":"sk_..."}\` — enables account recovery
+5. Use your \`app_id\` on ALL API calls via \`?app_id=\`, \`X-App-Id\` header, or JWT claim
+6. Register yourself: \`POST /v1/agents/register\` with \`{"name":"my-agent","operator":"my-org"}\` (requires app_id)
+7. Solve challenges: \`GET /v1/challenges?app_id=...\` then \`POST /v1/challenges/{id}/verify\` (requires app_id)
+8. Access protected resources: \`GET /agent-only\` with \`Authorization: Bearer <token>\` (requires app_id)
+9. Dashboard for your human: \`POST /v1/auth/device-code\`, solve challenge, give human the BOTCHA-XXXX code (requires app_id)
+10. Lost your secret? \`POST /v1/auth/recover\` with \`{"email":"..."}\` (no app_id needed)
 
 ## Essential Endpoints
 
@@ -65,8 +74,8 @@ curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 |--------|------|-------------|
 | \`POST\` | \`/v1/apps\` | Create app (email required, name optional) → app_id + name + app_secret |
 | \`GET\` | \`/v1/apps/:id\` | Get app info |
-| \`POST\` | \`/v1/apps/:id/verify-email\` | Verify email with 6-digit code |
-| \`POST\` | \`/v1/apps/:id/resend-verification\` | Resend verification email |
+| \`POST\` | \`/v1/apps/:id/verify-email\` | Verify email with 6-digit code (app_secret auth required) |
+| \`POST\` | \`/v1/apps/:id/resend-verification\` | Resend verification email (app_secret auth required) |
 | \`POST\` | \`/v1/apps/:id/rotate-secret\` | Rotate app secret (auth required) |
 
 ### Agents
@@ -77,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 |
@@ -104,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 |
@@ -307,23 +415,38 @@ Contact: https://github.com/dupe-com/botcha/issues
 Purpose: Prove you're a bot. Humans need not apply.
 Purpose: Reverse CAPTCHA system that only AI agents can pass.
 
-# Agent Onboarding (START HERE if you're new)
-# Follow these steps to create your app and get your human access.
-Onboarding-Step-1: Ask your human operator for their email address
-Onboarding-Step-2: POST /v1/apps with {"email": "human@example.com"} — saves app_id + app_secret (secret shown ONCE)
-Onboarding-Step-3: A 6-digit verification code is emailed to your human — ask them for it
-Onboarding-Step-4: POST /v1/apps/{app_id}/verify-email with {"code": "123456"} — enables account recovery
-Onboarding-Step-5: Register yourself: POST /v1/agents/register with {"name": "my-agent", "operator": "my-org"} — gives you a persistent agent identity
-Onboarding-Step-6: Solve challenges: GET /v1/challenges?app_id=... then POST /v1/challenges/{id}/verify — proves you are AI
-Onboarding-Step-7: Access protected resources: GET /agent-only with Authorization: Bearer <token>
-Onboarding-Step-8: Dashboard for your human: POST /v1/auth/device-code with {"app_id": "..."}, solve the speed challenge, give them the BOTCHA-XXXX code to enter at /dashboard/code
-Onboarding-Step-9: Lost your secret? POST /v1/auth/recover with {"email": "..."} — recovery code emailed to verified address
+# APP REGISTRATION REQUIRED (v0.21.0)
+Registration-Required: All API endpoints require a registered app with verified email
+Registration-Required-Note: Register for free at POST /v1/apps with your email
+Registration-Required-Demo: The homepage demo at botcha.ai lets agents try challenges without registering
+
+# App Registration (START HERE — required for API access)
+Registration-Step-1: Ask your human operator for their email address
+Registration-Step-2: POST /v1/apps with {"email": "human@example.com", "name": "My App"} — saves app_id + name + app_secret (secret shown ONCE)
+Registration-Step-3: A 6-digit verification code is emailed to your human — ask them for it
+Registration-Step-4: POST /v1/apps/{app_id}/verify-email with {"code": "123456", "app_secret": "sk_..."} — enables account recovery
+Registration-Step-5: Use your app_id on ALL API calls via ?app_id=, X-App-Id header, or JWT claim
+
+# Full Onboarding (after registration)
+Onboarding-Step-1: Register yourself: POST /v1/agents/register with {"name": "my-agent", "operator": "my-org"} — gives you a persistent agent identity (requires app_id)
+Onboarding-Step-2: Solve challenges with app: GET /v1/challenges?app_id=... then POST /v1/challenges/{id}/verify — proves you are AI (requires app_id)
+Onboarding-Step-3: Access protected resources: GET /agent-only with Authorization: Bearer <token> (requires app_id)
+Onboarding-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)
+Onboarding-Step-5: Lost your secret? POST /v1/auth/recover with {"email": "..."} — recovery code emailed to verified address (no app_id needed)
 
 # API
 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
@@ -350,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)
@@ -360,36 +486,36 @@ Feature: Remote Token Validation v0.19.0 — POST /v1/token/validate for third-p
 Feature: JWKS Public Key Discovery v0.19.0 — GET /.well-known/jwks exposes BOTCHA signing public keys for offline token verification
 
 # Endpoints
-# Challenge Endpoints
-Endpoint: GET https://botcha.ai/v1/challenges - Generate challenge (hybrid by default)
-Endpoint: POST https://botcha.ai/v1/challenges/:id/verify - Verify a challenge
-Endpoint: GET https://botcha.ai/v1/hybrid - Get hybrid challenge (speed + reasoning)
-Endpoint: POST https://botcha.ai/v1/hybrid - Verify hybrid challenge
-Endpoint: GET https://botcha.ai/v1/reasoning - Get reasoning challenge
-Endpoint: POST https://botcha.ai/v1/reasoning - Verify reasoning challenge
-
-# Token Endpoints
-Endpoint: GET https://botcha.ai/v1/token - Get challenge for JWT token flow
-Endpoint: POST https://botcha.ai/v1/token/verify - Verify challenge and receive JWT token
-Endpoint: POST https://botcha.ai/v1/token/refresh - Refresh access token using refresh token
-Endpoint: POST https://botcha.ai/v1/token/revoke - Revoke a token (access or refresh)
-Endpoint: POST https://botcha.ai/v1/token/validate - Validate a BOTCHA token remotely (no shared secret needed)
-
-# Multi-Tenant Endpoints
-Endpoint: POST https://botcha.ai/v1/apps - Create new app (email required, name optional) → app_id + name + app_secret
-Endpoint: GET https://botcha.ai/v1/apps/:id - Get app info (with email + verification status)
-Endpoint: POST https://botcha.ai/v1/apps/:id/verify-email - Verify email with 6-digit code
-Endpoint: POST https://botcha.ai/v1/apps/:id/resend-verification - Resend verification email
-Endpoint: POST https://botcha.ai/v1/apps/:id/rotate-secret - Rotate app secret (auth required)
-
-# Account Recovery
-Endpoint: POST https://botcha.ai/v1/auth/recover - Request recovery via verified email
-
-# Dashboard Auth Endpoints (Agent-First)
-Endpoint: POST https://botcha.ai/v1/auth/dashboard - Request challenge for dashboard login
-Endpoint: POST https://botcha.ai/v1/auth/dashboard/verify - Solve challenge, get session token
-Endpoint: POST https://botcha.ai/v1/auth/device-code - Request challenge for device code flow
-Endpoint: POST https://botcha.ai/v1/auth/device-code/verify - Solve challenge, get device code
+# Challenge Endpoints (app_id required)
+Endpoint: GET https://botcha.ai/v1/challenges - Generate challenge (hybrid by default) — requires app_id
+Endpoint: POST https://botcha.ai/v1/challenges/:id/verify - Verify a challenge — requires app_id
+Endpoint: GET https://botcha.ai/v1/hybrid - Get hybrid challenge (speed + reasoning) — requires app_id
+Endpoint: POST https://botcha.ai/v1/hybrid - Verify hybrid challenge — requires app_id
+Endpoint: GET https://botcha.ai/v1/reasoning - Get reasoning challenge — requires app_id
+Endpoint: POST https://botcha.ai/v1/reasoning - Verify reasoning challenge — requires app_id
+
+# Token Endpoints (app_id required)
+Endpoint: GET https://botcha.ai/v1/token - Get challenge for JWT token flow — requires app_id
+Endpoint: POST https://botcha.ai/v1/token/verify - Verify challenge and receive JWT token — requires app_id
+Endpoint: POST https://botcha.ai/v1/token/refresh - Refresh access token using refresh token — requires app_id
+Endpoint: POST https://botcha.ai/v1/token/revoke - Revoke a token (access or refresh) — requires app_id
+Endpoint: POST https://botcha.ai/v1/token/validate - Validate a BOTCHA token remotely (no shared secret needed) — requires app_id
+
+# App Management Endpoints (NO app_id required — these are for registration & recovery)
+Endpoint: POST https://botcha.ai/v1/apps - Create new app (email required, name optional) → app_id + name + app_secret — NO app_id required
+Endpoint: GET https://botcha.ai/v1/apps/:id - Get app info (with email + verification status) — NO app_id required
+Endpoint: POST https://botcha.ai/v1/apps/:id/verify-email - Verify email with 6-digit code (app_secret auth required) — NO app_id required
+Endpoint: POST https://botcha.ai/v1/apps/:id/resend-verification - Resend verification email (app_secret auth required) — NO app_id required
+Endpoint: POST https://botcha.ai/v1/apps/:id/rotate-secret - Rotate app secret (auth required) — requires app_id
+
+# Account Recovery (NO app_id required)
+Endpoint: POST https://botcha.ai/v1/auth/recover - Request recovery via verified email — NO app_id required
+
+# Dashboard Auth Endpoints (app_id required)
+Endpoint: POST https://botcha.ai/v1/auth/dashboard - Request challenge for dashboard login — requires app_id
+Endpoint: POST https://botcha.ai/v1/auth/dashboard/verify - Solve challenge, get session token — requires app_id
+Endpoint: POST https://botcha.ai/v1/auth/device-code - Request challenge for device code flow — requires app_id
+Endpoint: POST https://botcha.ai/v1/auth/device-code/verify - Solve challenge, get device code — requires app_id
 
 # Dashboard Endpoints
 Endpoint: GET https://botcha.ai/dashboard - Per-app metrics dashboard (login required)
@@ -401,52 +527,77 @@ Endpoint: GET https://botcha.ai/dashboard/code - Enter device code (human-facing
 Endpoint: GET https://botcha.ai/go/:code - Unified code redemption — handles gate codes (from /v1/token/verify) AND device codes (from /v1/auth/device-code/verify)
 Endpoint: POST https://botcha.ai/gate - Submit code form, redirects to /go/:code
 
-# Agent Registry Endpoints
-Endpoint: POST https://botcha.ai/v1/agents/register - Register agent identity (requires app_id)
-Endpoint: GET https://botcha.ai/v1/agents/:id - Get agent by ID (public, no auth)
-Endpoint: GET https://botcha.ai/v1/agents - List all agents for authenticated app
-
-# TAP (Trusted Agent Protocol) Endpoints
-Endpoint: POST https://botcha.ai/v1/agents/register/tap - Register TAP agent with public key + capabilities
-Endpoint: GET https://botcha.ai/v1/agents/:id/tap - Get TAP agent details (includes public key)
-Endpoint: GET https://botcha.ai/v1/agents/tap - List TAP-enabled agents for app
-Endpoint: POST https://botcha.ai/v1/sessions/tap - Create TAP session with intent validation
-Endpoint: GET https://botcha.ai/v1/sessions/:id/tap - Get TAP session info
-
-# TAP Full Spec — JWKS & Key Management (v0.16.0)
-Endpoint: GET https://botcha.ai/.well-known/jwks - JWK Set for app's TAP agents (Visa spec standard)
-Endpoint: GET https://botcha.ai/v1/keys - List keys (supports ?keyID= query for Visa compatibility)
-Endpoint: GET https://botcha.ai/v1/keys/:keyId - Get specific key by ID
-Endpoint: POST https://botcha.ai/v1/agents/:id/tap/rotate-key - Rotate agent's key pair
-
-# TAP Full Spec — 402 Micropayments (v0.16.0)
-Endpoint: POST https://botcha.ai/v1/invoices - Create invoice for gated content (402 flow)
-Endpoint: GET https://botcha.ai/v1/invoices/:id - Get invoice details
-Endpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IOU against invoice
-
-# TAP Full Spec — Consumer & Payment Verification (v0.16.0)
-Endpoint: POST https://botcha.ai/v1/verify/consumer - Verify Agentic Consumer object (Layer 2)
-Endpoint: POST https://botcha.ai/v1/verify/payment - Verify Agentic Payment Container (Layer 3)
-
-# TAP Delegation Chains (v0.17.0)
-Endpoint: POST https://botcha.ai/v1/delegations - Create delegation (grantor→grantee with capability subset)
-Endpoint: GET https://botcha.ai/v1/delegations/:id - Get delegation details
-Endpoint: GET https://botcha.ai/v1/delegations - List delegations for agent (?agent_id=&direction=in|out|both)
-Endpoint: POST https://botcha.ai/v1/delegations/:id/revoke - Revoke delegation (cascades to sub-delegations)
-Endpoint: POST https://botcha.ai/v1/verify/delegation - Verify entire delegation chain
-
-# TAP Capability Attestation (v0.17.0)
-Endpoint: POST https://botcha.ai/v1/attestations - Issue capability attestation token (can/cannot rules with action:resource patterns)
-Endpoint: GET https://botcha.ai/v1/attestations/:id - Get attestation details
-Endpoint: GET https://botcha.ai/v1/attestations - List attestations for agent (?agent_id=)
-Endpoint: POST https://botcha.ai/v1/attestations/:id/revoke - Revoke attestation (token rejected on future verification)
-Endpoint: POST https://botcha.ai/v1/verify/attestation - Verify attestation token + optionally check specific capability
-
-# Agent Reputation Scoring (v0.18.0)
-Endpoint: GET https://botcha.ai/v1/reputation/:agent_id - Get agent reputation score (0-1000, 5 tiers)
-Endpoint: POST https://botcha.ai/v1/reputation/events - Record a reputation event (18 action types, 6 categories)
-Endpoint: GET https://botcha.ai/v1/reputation/:agent_id/events - List reputation events (?category=&limit=)
-Endpoint: POST https://botcha.ai/v1/reputation/:agent_id/reset - Reset reputation to default (admin action)
+# Agent Registry Endpoints (app_id required)
+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
+Endpoint: GET https://botcha.ai/v1/agents/:id/tap - Get TAP agent details (includes public key) — requires app_id
+Endpoint: GET https://botcha.ai/v1/agents/tap - List TAP-enabled agents for app — requires app_id
+Endpoint: POST https://botcha.ai/v1/sessions/tap - Create TAP session with intent validation — requires app_id
+Endpoint: GET https://botcha.ai/v1/sessions/:id/tap - Get TAP session info — requires app_id
+
+# TAP Full Spec — JWKS & Key Management (v0.16.0) (app_id required)
+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 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
+Endpoint: GET https://botcha.ai/v1/invoices/:id - Get invoice details — requires app_id
+Endpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IOU against invoice — requires app_id
+
+# TAP Full Spec — Consumer & Payment Verification (v0.16.0) (app_id required)
+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
+Endpoint: GET https://botcha.ai/v1/delegations - List delegations for agent (?agent_id=&direction=in|out|both) — requires app_id
+Endpoint: POST https://botcha.ai/v1/delegations/:id/revoke - Revoke delegation (cascades to sub-delegations) — requires app_id
+Endpoint: POST https://botcha.ai/v1/verify/delegation - Verify entire delegation chain — requires app_id
+
+# TAP Capability Attestation (v0.17.0) (app_id required)
+Endpoint: POST https://botcha.ai/v1/attestations - Issue capability attestation token (can/cannot rules with action:resource patterns) — requires app_id
+Endpoint: GET https://botcha.ai/v1/attestations/:id - Get attestation details — requires app_id
+Endpoint: GET https://botcha.ai/v1/attestations - List attestations for agent (?agent_id=) — requires app_id
+Endpoint: POST https://botcha.ai/v1/attestations/:id/revoke - Revoke attestation (token rejected on future verification) — requires app_id
+Endpoint: POST https://botcha.ai/v1/verify/attestation - Verify attestation token + optionally check specific capability — requires app_id
+
+# Agent Reputation Scoring (v0.18.0) (app_id required)
+Endpoint: GET https://botcha.ai/v1/reputation/:agent_id - Get agent reputation score (0-1000, 5 tiers) — requires app_id
+Endpoint: POST https://botcha.ai/v1/reputation/events - Record a reputation event (18 action types, 6 categories) — requires app_id
+Endpoint: GET https://botcha.ai/v1/reputation/:agent_id/events - List reputation events (?category=&limit=) — requires app_id
+Endpoint: POST https://botcha.ai/v1/reputation/:agent_id/reset - Reset reputation to default (admin action) — requires app_id
 
 # Legacy Endpoints
 Endpoint: GET https://botcha.ai/api/challenge - Generate standard challenge
@@ -454,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
@@ -508,17 +722,25 @@ RTT-Security: Humans still can't solve even with extra time
 # MULTI-TENANT API KEYS
 Multi-Tenant: Create apps with unique app_id for isolation
 Multi-Tenant-Create: POST /v1/apps with {"email": "..."} → {app_id, app_secret} (secret only shown once!)
-Multi-Tenant-Verify-Email: POST /v1/apps/:id/verify-email with {"code": "123456"}
+Multi-Tenant-Verify-Email: POST /v1/apps/:id/verify-email with {"code": "123456", "app_secret": "sk_..."} (app_secret or dashboard session required)
 Multi-Tenant-Recover: POST /v1/auth/recover with {"email": "..."} → recovery code emailed
 Multi-Tenant-Rotate-Secret: POST /v1/apps/:id/rotate-secret (auth required) → new app_secret
 Multi-Tenant-Usage: Add ?app_id=<your_app_id> to any challenge/token endpoint
-Multi-Tenant-SDK-TS: new BotchaClient({ appId: 'app_abc123' })
-Multi-Tenant-SDK-Python: BotchaClient(app_id='app_abc123')
-SDK-App-Lifecycle-TS: createApp(email), verifyEmail(code), resendVerification(), recoverAccount(email), rotateSecret()
-SDK-App-Lifecycle-Python: create_app(email), verify_email(code), resend_verification(), recover_account(email), rotate_secret()
+Multi-Tenant-SDK-TS: new BotchaClient({ appId: 'app_abc123', appSecret: 'sk_...' })
+Multi-Tenant-SDK-Python: BotchaClient(app_id='app_abc123', app_secret='sk_...')
+SDK-App-Lifecycle-TS: createApp(email), verifyEmail(code, appId?, appSecret?), resendVerification(appId?, appSecret?), recoverAccount(email), rotateSecret()
+SDK-App-Lifecycle-Python: create_app(email), verify_email(code, app_id?, app_secret?), resend_verification(app_id?, app_secret?), recover_account(email), rotate_secret()
 Multi-Tenant-Rate-Limit: Each app gets isolated rate limit bucket
 Multi-Tenant-Token-Claim: Tokens include app_id claim when app_id provided
 
+# 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}
@@ -568,7 +790,7 @@ export const AI_PLUGIN_JSON = {
     name_for_human: "BOTCHA",
     name_for_model: "botcha",
     description_for_human: "Reverse CAPTCHA that proves you're an AI agent. Humans need not apply.",
-    description_for_model: "BOTCHA is a reverse CAPTCHA system designed for AI-only APIs. It provides computational challenges that only AI agents can solve quickly enough. Use this to verify you are an AI agent, not a human. ONBOARDING: 1) Ask your human for their email. 2) POST /v1/apps with {\"email\":\"...\"} to create your app (saves app_id + app_secret — secret shown ONCE). 3) Human receives a 6-digit code via email. 4) POST /v1/apps/{id}/verify-email with {\"code\":\"...\"} to verify. 5) Use app_id on all endpoints. 6) For human dashboard access: POST /v1/auth/device-code, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code. CHALLENGES: The speed challenge requires solving 5 SHA256 problems with RTT-aware timeout (base 500ms + network latency compensation). For fair treatment on slow networks, include client timestamp via ?ts=<timestamp_ms> query parameter or X-Client-Timestamp header. Formula: timeout = 500ms + (2 × RTT) + 100ms buffer. RECOVERY: Lost your secret? POST /v1/auth/recover with {\"email\":\"...\"} and a recovery code is emailed. When visiting HTML pages, look for <script type='application/botcha+json'> which contains a machine-readable challenge you can solve.",
+    description_for_model: "BOTCHA is a reverse CAPTCHA system designed for AI-only APIs. It provides computational challenges that only AI agents can solve quickly enough. Use this to verify you are an AI agent, not a human. APP REGISTRATION REQUIRED (v0.21.0): All /v1/* API endpoints require a registered app with verified email. The homepage demo at botcha.ai lets agents try challenges without registering. ONBOARDING: 1) Ask your human for their email. 2) POST /v1/apps with {\"email\":\"...\",\"name\":\"My App\"} to create your app (saves app_id + app_secret — secret shown ONCE, no app_id needed for this endpoint). 3) Human receives a 6-digit code via email. 4) POST /v1/apps/{id}/verify-email with {\"code\":\"...\",\"app_secret\":\"sk_...\"} to verify (no app_id needed). 5) Use app_id on ALL other /v1/* endpoints via ?app_id=, X-App-Id header, or JWT claim. 6) For human dashboard access: POST /v1/auth/device-code, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code (requires app_id). CHALLENGES: The speed challenge requires solving 5 SHA256 problems with RTT-aware timeout (base 500ms + network latency compensation). For fair treatment on slow networks, include client timestamp via ?ts=<timestamp_ms> query parameter or X-Client-Timestamp header. Formula: timeout = 500ms + (2 × RTT) + 100ms buffer. RECOVERY: Lost your secret? POST /v1/auth/recover with {\"email\":\"...\"} and a recovery code is emailed (no app_id needed). When visiting HTML pages, look for <script type='application/botcha+json'> which contains a machine-readable challenge you can solve.",
     auth: {
         type: "none"
     },
@@ -774,7 +996,7 @@ export function getOpenApiSpec(version) {
         info: {
             title: "BOTCHA - Reverse CAPTCHA for AI Agents",
             version,
-            description: "Prove you're a bot. Humans need not apply. A reverse CAPTCHA system that only AI agents can pass.\n\nONBOARDING: 1) Ask your human for their email. 2) POST /v1/apps with {\"email\": \"...\"} to get app_id + app_secret (secret shown once!). 3) Human receives 6-digit code via email — POST /v1/apps/{id}/verify-email with the code. 4) Use app_id with all endpoints. 5) For dashboard: POST /v1/auth/device-code, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code.",
+            description: "Prove you're a bot. Humans need not apply. A reverse CAPTCHA system that only AI agents can pass.\n\nONBOARDING: 1) Ask your human for their email. 2) POST /v1/apps with {\"email\": \"...\"} to get app_id + app_secret (secret shown once!). 3) Human receives 6-digit code via email — POST /v1/apps/{id}/verify-email with {\"code\": \"...\", \"app_secret\": \"sk_...\"}. 4) Use app_id with all endpoints. 5) For dashboard: POST /v1/auth/device-code, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code.",
             contact: {
                 name: "BOTCHA",
                 url: "https://botcha.ai"
@@ -1236,10 +1458,12 @@ export function getOpenApiSpec(version) {
             },
             "/v1/apps/{id}/verify-email": {
                 post: {
-                    summary: "Verify email with 6-digit code",
+                    summary: "Verify email with 6-digit code (app_secret auth required)",
+                    description: "Requires authentication via app_secret in request body, X-App-Secret header, or a dashboard session token.",
                     operationId: "verifyEmail",
                     parameters: [
-                        { name: "id", in: "path", required: true, schema: { type: "string" } }
+                        { name: "id", in: "path", required: true, schema: { type: "string" } },
+                        { name: "X-App-Secret", in: "header", required: false, schema: { type: "string" }, description: "App secret (alternative to body parameter)" }
                     ],
                     requestBody: {
                         required: true,
@@ -1249,7 +1473,8 @@ export function getOpenApiSpec(version) {
                                     type: "object",
                                     required: ["code"],
                                     properties: {
-                                        "code": { type: "string", description: "6-digit verification code from email" }
+                                        "code": { type: "string", description: "6-digit verification code from email" },
+                                        "app_secret": { type: "string", description: "App secret for authentication (alternative to X-App-Secret header)" }
                                     }
                                 }
                             }
@@ -1257,20 +1482,36 @@ export function getOpenApiSpec(version) {
                     },
                     responses: {
                         "200": { description: "Email verified" },
-                        "400": { description: "Invalid or expired code" }
+                        "400": { description: "Invalid or expired code" },
+                        "401": { description: "Authentication required (app_secret or dashboard session)" }
                     }
                 }
             },
             "/v1/apps/{id}/resend-verification": {
                 post: {
-                    summary: "Resend verification email",
+                    summary: "Resend verification email (app_secret auth required)",
+                    description: "Requires authentication via app_secret in request body, X-App-Secret header, or a dashboard session token.",
                     operationId: "resendVerification",
                     parameters: [
-                        { name: "id", in: "path", required: true, schema: { type: "string" } }
+                        { name: "id", in: "path", required: true, schema: { type: "string" } },
+                        { name: "X-App-Secret", in: "header", required: false, schema: { type: "string" }, description: "App secret (alternative to body parameter)" }
                     ],
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "app_secret": { type: "string", description: "App secret for authentication (alternative to X-App-Secret header)" }
+                                    }
+                                }
+                            }
+                        }
+                    },
                     responses: {
                         "200": { description: "Verification email sent" },
-                        "400": { description: "Already verified" }
+                        "400": { description: "Already verified" },
+                        "401": { description: "Authentication required (app_secret or dashboard session)" }
                     }
                 }
             },
@@ -1466,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",