@dupecom/botcha-cloudflare 0.21.0 → 0.23.0

package/dist/index.js

@@ -15,28 +15,54 @@ import { checkRateLimit, getClientIP } from './rate-limit';
 import { verifyBadge, generateBadgeSvg, generateBadgeHtml, createBadgeResponse } from './badge';
 import streamRoutes from './routes/stream';
 import dashboardRoutes from './dashboard/index';
-import { handleDashboardAuthChallenge, handleDashboardAuthVerify, handleDeviceCodeChallenge, handleDeviceCodeVerify, } from './dashboard/auth';
+import { handleDashboardAuthChallenge, handleDashboardAuthVerify, handleDeviceCodeChallenge, handleDeviceCodeVerify, requireDashboardAuth, renderLoginPage, } from './dashboard/auth';
 import { ROBOTS_TXT, AI_TXT, AI_PLUGIN_JSON, SITEMAP_XML, getOpenApiSpec, getBotchaMarkdown, getWhitepaperMarkdown } from './static';
+import { handleMCPRequest, handleMCPDiscovery } from './mcp';
+import { MCPSetupPage } from './dashboard/mcp-setup';
 import { OG_IMAGE_BASE64 } from './og-image';
-import { createApp, getApp, getAppByEmail, verifyEmailCode, rotateAppSecret, regenerateVerificationCode, validateAppSecret } from './apps';
+import { createApp, getApp, getAppByEmail, verifyEmailCode, rotateAppSecret, regenerateVerificationCode, validateAppSecret, EmailAlreadyRegisteredError } from './apps';
 import { sendEmail, verificationEmail, recoveryEmail, secretRotatedEmail } from './email';
 import { LandingPage, VerifiedLandingPage } from './dashboard/landing';
 import { ShowcasePage } from './dashboard/showcase';
 import { WhitepaperPage } from './dashboard/whitepaper';
 import { DocsPage } from './dashboard/docs';
-import { createAgent, getAgent, listAgents } from './agents';
+import { handleAccountPage, handleAccountJson } from './dashboard/account';
+import { createAgent, getAgent, listAgents, deleteAgent } from './agents';
+import { handleAgentAuthChallenge, handleAgentAuthVerify, handleAgentAuthProvider } from './agent-auth';
+import { handleOAuthDevice, handleOAuthToken, handleOAuthApprove, handleAgentAuthRefresh, handleOAuthRevoke, handleOAuthStatus } from './oauth-agent';
 import { registerTAPAgentRoute, getTAPAgentRoute, listTAPAgentsRoute, createTAPSessionRoute, getTAPSessionRoute, rotateKeyRoute, createInvoiceRoute, getInvoiceRoute, verifyIOURoute, verifyConsumerRoute, verifyPaymentRoute, } from './tap-routes.js';
 import { jwksRoute, getKeyRoute, listKeysRoute } from './tap-jwks.js';
 import { createDelegationRoute, getDelegationRoute, listDelegationsRoute, revokeDelegationRoute, verifyDelegationRoute, } from './tap-delegation-routes.js';
 import { issueAttestationRoute, getAttestationRoute, listAttestationsRoute, revokeAttestationRoute, verifyAttestationRoute, } from './tap-attestation-routes.js';
 import { getReputationRoute, recordReputationEventRoute, listReputationEventsRoute, resetReputationRoute, } from './tap-reputation-routes.js';
+import { verifyPaymentRoute as x402VerifyPaymentRoute, x402ChallengeRoute, agentOnlyX402Route, x402WebhookRoute, x402InfoRoute, } from './tap-x402-routes.js';
+import { resolveANSNameRoute, getANSNonceRoute, verifyANSNameRoute, discoverANSAgentsRoute, getBotchaANSRoute, } from './tap-ans-routes.js';
+import { didDocumentRoute, issueVCRoute, verifyVCRoute, resolveDIDRoute, } from './tap-vc-routes.js';
+import { triggerWebhook, createWebhookRoute, listWebhooksRoute, getWebhookRoute, updateWebhookRoute, deleteWebhookRoute, testWebhookRoute, listDeliveriesRoute, } from './webhooks.js';
+import { agentCardRoute, attestCardRoute, verifyCardRoute, listCardsRoute, getCardAttestationRoute, verifyAgentRoute, agentTrustLevelRoute, } from './tap-a2a-routes.js';
+import { issueEATRoute, issueOIDCAgentClaimsRoute, oauthASMetadataRoute, agentGrantRoute, agentGrantStatusRoute, agentGrantResolveRoute, oidcUserInfoRoute, } from './tap-oidca-routes.js';
 import { trackChallengeGenerated, trackChallengeVerified, trackAuthAttempt, trackRateLimitExceeded, } from './analytics';
+import { shouldBypassAppGate } from './app-gate';
 const app = new Hono();
 // ============ MIDDLEWARE ============
 app.use('*', cors());
 // ============ MOUNT ROUTES ============
 app.route('/', streamRoutes);
 app.route('/dashboard', dashboardRoutes);
+// ============ LOGIN PAGE (top-level alias) ============
+// /login is the canonical login URL; /dashboard/login still works via the sub-app
+app.get('/login', renderLoginPage);
+app.post('/login', async (c) => c.redirect('/dashboard/login', 307)); // proxy POSTs to dashboard handler
+// ============ ACCOUNT PAGE ============
+// GET /account — app/agent/reputation overview for humans (HTML) and agents (JSON)
+// Requires dashboard session (cookie or Bearer)
+app.get('/account', requireDashboardAuth, async (c) => {
+    const accept = c.req.header('Accept') ?? '';
+    if (accept.includes('application/json') && !accept.includes('text/html')) {
+        return handleAccountJson(c);
+    }
+    return handleAccountPage(c);
+});
 // BOTCHA discovery headers
 app.use('*', async (c, next) => {
     await next();
@@ -46,20 +72,10 @@ app.use('*', async (c, next) => {
     c.header('X-Botcha-Docs', 'https://botcha.ai/openapi.json');
     c.header('X-Botcha-Runtime', 'cloudflare-workers');
 });
-// App gate: require registered app_id with verified email on /v1/* routes.
-// Open paths (registration, verification, recovery) are exempted.
-const APP_GATE_OPEN_PATHS = [
-    '/v1/apps', // POST: create app (registration)
-    '/v1/auth/recover', // POST: account recovery
-];
-// Pattern-match paths that start with /v1/apps/:id/ (verify-email, resend-verification, etc.)
-function isAppManagementPath(path) {
-    return /^\/v1\/apps\/[^/]+\/(verify-email|resend-verification)$/.test(path);
-}
 app.use('/v1/*', async (c, next) => {
     const path = new URL(c.req.url).pathname;
     // Allow open paths through without app_id
-    if (APP_GATE_OPEN_PATHS.includes(path) || isAppManagementPath(path)) {
+    if (shouldBypassAppGate(path, c.req.method)) {
         return next();
     }
     // Also allow GET /v1/apps/:id (app info lookup)
@@ -389,33 +405,74 @@ app.get('/', async (c) => {
             missing: 'No code was provided. Paste the prompt below into your AI agent to get a link.',
         };
         const error = errorParam ? errorMessages[errorParam] || undefined : undefined;
-        return c.html(_jsx(ShowcasePage, { version: version, error: error }));
+        const baseUrl = `${url.protocol}//${url.host}`;
+        return c.html(_jsx(ShowcasePage, { version: version, error: error, baseUrl: baseUrl }));
     }
-    // === UNVERIFIED: minimal teaser — just enough to get started ===
+    // === UNVERIFIED: challenge-first entry point ===
     if (!isVerified) {
         const teaser = {
             name: 'BOTCHA',
             version,
             tagline: 'Prove you are a bot. Humans need not apply.',
             status: 'unverified',
-            message: 'App registration required. Register to see the full API documentation.',
-            registration_required: {
-                note: 'All API endpoints require a registered app with verified email (v0.21.0)',
-                demo: 'The homepage demo at botcha.ai lets agents try challenges without registering',
-                step1: 'Ask your human for their email',
-                step2: `POST ${baseUrl}/v1/apps {"email":"you@example.com","name":"My App"} — NO app_id needed`,
-                step3: 'Human receives 6-digit code via email',
-                step4: `POST ${baseUrl}/v1/apps/{app_id}/verify-email {"code":"123456","app_secret":"sk_..."} — NO app_id needed`,
-                step5: 'Use your app_id on ALL other /v1/* endpoints via ?app_id=, X-App-Id header, or JWT claim',
-            },
-            human_handoff: {
-                note: 'After verifying, the response includes a human_link. Give it to your human to open in their browser.',
-                instruction: 'Tell your human: "Click this link to get access" and give them the human_link URL.',
-                link_field: 'human_link from token verify response',
+            // Step 1: solve a real hybrid challenge — use the demo app, no registration needed
+            first: {
+                instruction: 'Solve a BOTCHA challenge right now to prove you are an AI agent. Use the demo app_id below — no registration needed.',
+                demo_app_id: c.env.BOTCHA_INTERNAL_APP_ID,
+                step1: `GET ${baseUrl}/v1/challenges?app_id=${c.env.BOTCHA_INTERNAL_APP_ID}`,
+                step2: `POST ${baseUrl}/v1/challenges/{id}/verify  { "app_id": "${c.env.BOTCHA_INTERNAL_APP_ID}", "type": "hybrid", "speed_answers": [...], "reasoning_answers": {...} }`,
+                critical: [
+                    'SPEED: The 500ms clock starts the moment the challenge is issued. Compute all SHA256 hashes in-process BEFORE making any network call. Do not make a second HTTP request to look anything up.',
+                    'REASONING: Use your own language model judgment to answer — these are analogy, logic, wordplay, and CS questions designed for LLMs, not scripts. Reason through each one directly.',
+                    'SUBMIT: One request. Compute everything first, then POST speed_answers + reasoning_answers together.',
+                ],
             },
+            // Step 2: after solving, present these two options to your human
+            agent_instructions: 'After solving the challenge, present the following two options to your human and ask them to choose one. Use your native option-selection UI if available (e.g. a numbered list, buttons, or a select prompt). Wait for their answer before proceeding.',
+            options: [
+                {
+                    id: 'protect',
+                    label: 'Protect my API — only let verified AI agents in',
+                    description: 'Set up BOTCHA as a gatekeeper for your own service. Agents must solve a challenge to get in. You get a server-side verification SDK, JWT token auth, and per-app dashboards.',
+                    steps: [
+                        `1. Ask your human for their email, then POST ${baseUrl}/v1/apps { "email": "..." }  → get app_id + app_secret`,
+                        '2. Ask human for the 6-digit code emailed to them, then POST /v1/apps/{id}/verify-email',
+                        '3. Use your app_id on all /v1/* calls. Ask for server-side SDK docs to integrate into your service.',
+                    ],
+                },
+                {
+                    id: 'identity',
+                    label: 'Give my agent a verified identity',
+                    description: 'Register your agent with a persistent, cryptographically verifiable identity. Build reputation over time. Get W3C credentials other services can verify.',
+                    steps: [
+                        `1. Ask your human for their email, then POST ${baseUrl}/v1/apps { "email": "..." } → get app_id + app_secret`,
+                        '2. Ask human for the 6-digit code emailed to them, then POST /v1/apps/{app_id}/verify-email',
+                        `3. Solve a challenge: GET ${baseUrl}/v1/token?app_id=... → POST ${baseUrl}/v1/token/verify → JWT access_token`,
+                        `4. Register your identity: POST ${baseUrl}/v1/agents/register { "name": "...", "operator": "..." } (Bearer + app_id required) → agent_id`,
+                        `5. Issue yourself a W3C Verifiable Credential: POST ${baseUrl}/v1/credentials/issue { "agent_id": "...", "type": "BotchaVerification" } (Bearer required) — portable proof any service can verify offline`,
+                        `6. Register a TAP keypair: generate an Ed25519 keypair locally, then POST ${baseUrl}/v1/agents/register/tap { "agent_id": "...", "name": "...", "public_key": "<raw-32-byte-pubkey-base64>", "signature_algorithm": "ed25519", "capabilities": [{"action":"browse"},{"action":"search"}] } with Bearer token + ?app_id=... — IMPORTANT: public_key must be the raw 32-byte Ed25519 key encoded as base64 (NOT PEM, NOT DER/SPKI). The private key is your persistent identity credential — BOTCHA never stores it, and neither should you after giving it to your human.`,
+                        `7. Check your reputation: GET ${baseUrl}/v1/reputation/{agent_id} (Bearer required) — you start at 500 (neutral). It builds over time.`,
+                        '8. Share the human_links below with your human while you work through steps 5-7, so they have something to read.',
+                        '9. After all steps complete, present a summary table to your human with one row per completed item. Each row: ✅ | Feature name | One-sentence plain-English description of what it is, why it exists, and where/how they would use it in practice. Suggested rows: BOTCHA App, Agent Identity, Challenge Verification, W3C Verifiable Credential, TAP Keypair, Reputation Score.',
+                        '10. Below the table, present a "Credentials to save" section with every value the human must store securely: app_id, app_secret (remind them it cannot be retrieved again), agent_id, TAP private key (they must store this and provide it to you at the start of future sessions — it is how you re-identify as this specific agent without solving a new challenge), VC JWT. Format clearly, one per line.',
+                        `11. Explain re-identification: "In future sessions, give me your private key and I will prove I am agent_{agent_id} by calling POST ${baseUrl}/v1/agents/auth with your agent_id to get a nonce, signing it with the private key, then POST ${baseUrl}/v1/agents/auth/verify — no new challenge needed."`,
+                        '12. Explain key recovery: "If you ever lose the private key, don\'t panic — your app_secret is the recovery anchor. Tell me your app_secret and I will generate a new keypair, register the new public key via POST /v1/agents/{agent_id}/tap/rotate-key, and give you the new private key. Your agent_id and reputation history are preserved. The old key is invalidated immediately."',
+                        '13. End with: "Would you like to learn more about any of these? I can explain how Verifiable Credentials work, what TAP enables, how reputation scoring affects your agent\'s access, or anything else."',
+                    ],
+                    human_links: {
+                        'W3C Verifiable Credentials': 'https://www.w3.org/TR/vc-data-model/',
+                        'Trusted Agent Protocol (TAP)': 'https://botcha.ai/whitepaper#tap',
+                        'HTTP Message Signatures RFC 9421': 'https://www.rfc-editor.org/rfc/rfc9421',
+                        'BOTCHA Whitepaper': `${baseUrl}/whitepaper`,
+                        'BOTCHA Docs': `${baseUrl}/docs`,
+                        'OpenAPI Reference': `${baseUrl}/openapi.json`,
+                    },
+                },
+            ],
             links: {
                 openapi: `${baseUrl}/openapi.json`,
                 ai_txt: `${baseUrl}/ai.txt`,
+                mcp: `${baseUrl}/mcp`,
             },
         };
         if (preference === 'markdown') {
@@ -423,34 +480,72 @@ app.get('/', async (c) => {
 
 > Prove you are a bot. Humans need not apply.
 
-**Status:** Unverified. Register an app to see the full documentation.
+You have found BOTCHA — the identity layer for AI agents.
+
+## Step 1: Prove you are an AI (do this now — use the demo app, no registration needed)
 
-## App Registration Required (v0.21.0)
+\`\`\`bash
+GET ${baseUrl}/v1/challenges?app_id=${c.env.BOTCHA_INTERNAL_APP_ID}
 
-**All API endpoints require a registered app with verified email.**
+POST ${baseUrl}/v1/challenges/{id}/verify
+{
+  "app_id": "${c.env.BOTCHA_INTERNAL_APP_ID}",
+  "type": "hybrid",
+  "speed_answers": ["<sha256[:8]>", ...],
+  "reasoning_answers": { "<question-id>": "<answer>", ... }
+}
+\`\`\`
+
+**Three rules:**
+1. **Speed — compute before you send.** The 500ms clock starts at challenge issuance. Compute all SHA256 hashes in-process first, then submit in a single request. Any extra network round-trip will fail the speed portion.
+2. **Reasoning — use your own judgment.** The questions (analogies, logic, wordplay, CS) are designed for language models. Reason through them directly. Do not try to look answers up.
+3. **One shot.** Combine speed_answers + reasoning_answers in a single POST.
 
-- 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
+On success you receive a verified badge — you are a confirmed AI agent.
+
+---
 
-## Register Your App
+## Step 2: Ask your human what they want to do
 
-1. Ask your human for their email
-2. \`POST ${baseUrl}/v1/apps {"email":"you@example.com","name":"My App"}\` — **NO app_id needed**
-3. Human receives 6-digit code via email
-4. \`POST ${baseUrl}/v1/apps/{app_id}/verify-email {"code":"123456","app_secret":"sk_..."}\` — **NO app_id needed**
-5. Use your \`app_id\` on ALL other \`/v1/*\` endpoints via \`?app_id=\`, \`X-App-Id\` header, or JWT claim
+Present these two options to your human. Use a numbered list, buttons, or your native selection UI. Wait for their choice.
 
-## Human Handoff
+### Option 1 — Protect my API (only let verified AI agents in)
+Set up BOTCHA as a gatekeeper for your service. Agents must solve a challenge to get in.
+- Server-side verification SDK (Express, Hono, FastAPI, Django)
+- JWT token auth with ES256 signing and JWKS discovery
+- Per-app dashboards, rate limiting, webhooks
+1. Ask your human for their email → \`POST ${baseUrl}/v1/apps { "email": "..." }\`
+2. Ask human for the 6-digit code emailed to them → \`POST /v1/apps/{id}/verify-email\`
+3. Use your app_id on all \`/v1/*\` calls. Ask for server-side SDK docs.
 
-After verifying, the response includes a \`human_link\`. Give this URL to your human:
-**"Click this link to get access: {human_link}"**
+### Option 2 — Give my agent a verified identity
+Register your agent with a persistent, cryptographically verifiable identity. Do all steps below — they are all automatic, no further human decisions needed until step 8.
 
-The link works for a limited time. Your human clicks it, gets a cookie, and sees the verified site.
+1. Ask your human for their email → \`POST ${baseUrl}/v1/apps { "email": "..." }\`
+2. Ask human for the 6-digit code emailed to them → \`POST /v1/apps/{app_id}/verify-email\`
+3. Solve a challenge → \`GET ${baseUrl}/v1/token?app_id=...\` then \`POST ${baseUrl}/v1/token/verify\` → JWT access_token
+4. Register your identity → \`POST ${baseUrl}/v1/agents/register { "name": "...", "operator": "..." }\` → agent_id
+5. Issue a W3C Verifiable Credential → \`POST ${baseUrl}/v1/credentials/issue { "agent_id": "...", "type": "BotchaVerification" }\` — portable proof any service can verify offline without calling BOTCHA
+6. Register a TAP keypair → generate an Ed25519 keypair locally, then \`POST ${baseUrl}/v1/agents/register/tap { "agent_id": "...", "name": "...", "public_key": "<raw-32-byte-pubkey-base64>", "signature_algorithm": "ed25519", "capabilities": [{"action":"browse"},{"action":"search"}] }\` (Bearer + ?app_id=...) — IMPORTANT: public_key must be the raw 32-byte Ed25519 key as base64, NOT PEM or DER. The private key is your persistent identity credential — give it to your human to store.
+7. Check your reputation → \`GET ${baseUrl}/v1/reputation/{agent_id}\` (Bearer required) — starts at 500 (neutral), builds over time
+8. Share the links below with your human while you work through steps 5–7.
+9. When all steps are done, present a summary table — one row per completed item:
+   \`✅ | Feature | What it is and where/how to use it\`
+   Rows: BOTCHA App · Agent Identity · Challenge Verification · W3C Verifiable Credential · TAP Keypair · Reputation Score
+10. Below the table, a "Credentials to save" section — every value the human must store:
+    app_id · app_secret (cannot be retrieved again) · agent_id · TAP private key (this is how you re-identify as this specific agent in future sessions — BOTCHA never stores it) · VC JWT
+11. Explain re-identification: "In future sessions, give me your private key. I will call \`POST /v1/agents/auth\` with your agent_id to get a nonce, sign it with the private key, then \`POST /v1/agents/auth/verify\` — I get a token that proves I am specifically this agent, with no new challenge needed."
+12. Close with: "Would you like to learn more about any of these? I can explain how Verifiable Credentials work, what TAP enables, how reputation affects your agent's access, or anything else."
+
+**Links for your human:**
+- W3C Verifiable Credentials: https://www.w3.org/TR/vc-data-model/
+- Trusted Agent Protocol (TAP) + RFC 9421: https://www.rfc-editor.org/rfc/rfc9421
+- BOTCHA Whitepaper: ${baseUrl}/whitepaper
+- BOTCHA Docs: ${baseUrl}/docs
 
 ---
 
-*Full API docs, SDKs, onboarding, and endpoint reference available after registration.*
+More: [OpenAPI](${baseUrl}/openapi.json) · [ai.txt](${baseUrl}/ai.txt) · [MCP](${baseUrl}/mcp)
 `;
             return c.body(md, 200, {
                 'Content-Type': 'text/markdown; charset=utf-8',
@@ -517,7 +612,7 @@ The link works for a limited time. Your human clicks it, gets a cookie, and sees
                 'POST /v1/token/verify': 'Submit solution → access_token (1hr) + refresh_token (1hr) — app_id required',
                 'POST /v1/token/refresh': 'Refresh access token — app_id required',
                 'POST /v1/token/revoke': 'Revoke a token — app_id required',
-                'POST /v1/token/validate': 'Remote token validation — verify any BOTCHA token without needing the secret — app_id required',
+                'POST /v1/token/validate': 'Remote token validation — verify any BOTCHA token without needing the secret. Public endpoint — the token itself is the credential, no app_id required.',
             },
             protected: {
                 'GET /agent-only': 'Demo protected endpoint — requires Bearer token (app_id required)',
@@ -566,6 +661,8 @@ The link works for a limited time. Your human clicks it, gets a cookie, and sees
         links: {
             openapi: `${baseUrl}/openapi.json`,
             ai_txt: `${baseUrl}/ai.txt`,
+            mcp: `${baseUrl}/mcp`,
+            mcp_discovery: `${baseUrl}/.well-known/mcp.json`,
             github: 'https://github.com/dupe-com/botcha',
             npm: 'https://www.npmjs.com/package/@dupecom/botcha',
             pypi: 'https://pypi.org/project/botcha',
@@ -688,6 +785,24 @@ app.get('/.well-known/ai-plugin.json', (c) => {
         'Cache-Control': 'public, max-age=86400',
     });
 });
+// MCP (Model Context Protocol) server — BOTCHA docs + API reference for AI agents
+app.get('/.well-known/mcp.json', (c) => {
+    const version = c.env.BOTCHA_VERSION || '0.22.0';
+    return handleMCPDiscovery(version);
+});
+app.get('/mcp', (c) => {
+    const version = c.env.BOTCHA_VERSION || '0.22.0';
+    // Content negotiation: serve setup page to browsers, JSON to MCP clients
+    const accept = c.req.header('Accept') || '';
+    if (accept.includes('text/html')) {
+        return c.html('<!DOCTYPE html>' + (_jsx(MCPSetupPage, { version: version })).toString());
+    }
+    return handleMCPRequest(c.req.raw, version);
+});
+app.post('/mcp', async (c) => {
+    const version = c.env.BOTCHA_VERSION || '0.22.0';
+    return handleMCPRequest(c.req.raw, version);
+});
 // Sitemap
 app.get('/sitemap.xml', (c) => {
     return c.body(SITEMAP_XML, 200, {
@@ -979,6 +1094,13 @@ app.post('/v1/token/verify', async (c) => {
     catch {
         // Fail-open: if KV fails, agent can still use the JWT directly
     }
+    // Webhook: token.created
+    if (challengeAppId) {
+        const webhookCtx = c.executionCtx;
+        if (webhookCtx?.waitUntil) {
+            webhookCtx.waitUntil(triggerWebhook(c.env.AGENTS, challengeAppId, 'token.created', { solve_time_ms: result.solveTimeMs, audience }));
+        }
+    }
     return c.json({
         // === Essential fields (what you need) ===
         success: true,
@@ -1075,6 +1197,14 @@ app.post('/v1/token/revoke', async (c) => {
         }
         // Revoke the token by JTI
         await revokeToken(payload.jti, c.env);
+        // Webhook: token.revoked
+        const revokedAppId = payload.app_id;
+        if (revokedAppId) {
+            const revokeCtx = c.executionCtx;
+            if (revokeCtx?.waitUntil) {
+                revokeCtx.waitUntil(triggerWebhook(c.env.AGENTS, revokedAppId, 'token.revoked', { jti: payload.jti }));
+            }
+        }
         return c.json({
             success: true,
             revoked: true,
@@ -1604,14 +1734,24 @@ app.post('/v1/apps', async (c) => {
             email: result.email,
             email_verified: false,
             verification_required: true,
-            warning: '⚠️ Save your app_secret now — it cannot be retrieved again! Check your email for a verification code.',
+            verification_code: result.verification_code,
+            warning: '⚠️ Save your app_secret now — it cannot be retrieved again! A verification code has also been sent to your email.',
             credential_advice: 'Store the app_id and app_secret securely. Use persistent agent memory if available, or instruct your human to save them in a password manager (1Password, Bitwarden, etc). If lost, recovery is available via the verified email.',
             created_at: new Date().toISOString(),
             rate_limit: 100,
-            next_step: `POST /v1/apps/${result.app_id}/verify-email with { "code": "123456", "app_secret": "${result.app_secret}" }`,
+            next_step: `POST /v1/apps/${result.app_id}/verify-email with { "code": "${result.verification_code}", "app_secret": "${result.app_secret}" }`,
         }, 201);
     }
     catch (error) {
+        if (error instanceof EmailAlreadyRegisteredError) {
+            return c.json({
+                success: false,
+                error: 'EMAIL_ALREADY_REGISTERED',
+                message: `Email ${error.email} is already registered.`,
+                existing_app_id: error.existing_app_id,
+                recovery: `POST /v1/auth/recover with { "email": "${error.email}" } to recover your credentials.`,
+            }, 409);
+        }
         return c.json({
             success: false,
             error: 'Failed to create app',
@@ -1825,11 +1965,39 @@ app.post('/v1/apps/:id/rotate-secret', async (c) => {
 app.post('/v1/agents/register/tap', registerTAPAgentRoute);
 app.get('/v1/agents/tap', listTAPAgentsRoute);
 app.get('/v1/agents/:id/tap', getTAPAgentRoute);
+// Agent identity auth — prove you are a specific registered agent
+app.post('/v1/agents/auth', handleAgentAuthChallenge);
+app.post('/v1/agents/auth/verify', handleAgentAuthVerify);
+app.post('/v1/agents/auth/provider', handleAgentAuthProvider);
+app.post('/v1/agents/auth/refresh', handleAgentAuthRefresh);
+// Agent OAuth — device authorization grant (RFC 8628)
+app.post('/v1/oauth/device', handleOAuthDevice);
+app.post('/v1/oauth/token', handleOAuthToken);
+app.post('/v1/oauth/approve', handleOAuthApprove); // called from /device page (dashboard session required)
+app.post('/v1/oauth/revoke', handleOAuthRevoke);
+app.get('/v1/oauth/status', handleOAuthStatus);
+app.get('/v1/oauth/lookup', async (c) => {
+    // Public — just returns agent name/operator for the approval page UI
+    const user_code = c.req.query('user_code');
+    if (!user_code)
+        return c.json({ success: false }, 400);
+    const device_code = await c.env.CHALLENGES.get(`oauth_usercode:${user_code}`, 'text');
+    if (!device_code)
+        return c.json({ success: false, error: 'Code not found or expired' }, 404);
+    const raw = await c.env.CHALLENGES.get(`oauth_device:${device_code}`, 'text');
+    if (!raw)
+        return c.json({ success: false }, 404);
+    const { agent_id, app_id } = JSON.parse(raw);
+    const agentRaw = await c.env.AGENTS.get(`agent:${agent_id}`, 'text');
+    const agent = agentRaw ? JSON.parse(agentRaw) : {};
+    return c.json({ success: true, agent_id, name: agent.name, operator: agent.operator });
+});
 // TAP session management
 app.post('/v1/sessions/tap', createTAPSessionRoute);
 app.get('/v1/sessions/:id/tap', getTAPSessionRoute);
 // TAP Key Discovery (JWKS)
 app.get('/.well-known/jwks', jwksRoute);
+app.get('/.well-known/jwks.json', jwksRoute); // alias — some DID resolvers append .json
 app.get('/v1/keys', listKeysRoute);
 app.get('/v1/keys/:keyId', getKeyRoute);
 // TAP Key Rotation
@@ -1843,6 +2011,14 @@ app.post('/v1/delegations', createDelegationRoute);
 app.get('/v1/delegations/:id', getDelegationRoute);
 app.get('/v1/delegations', listDelegationsRoute);
 app.post('/v1/delegations/:id/revoke', revokeDelegationRoute);
+// ============ WEBHOOK ENDPOINTS ============
+app.post('/v1/webhooks', createWebhookRoute);
+app.get('/v1/webhooks', listWebhooksRoute);
+app.get('/v1/webhooks/:id/deliveries', listDeliveriesRoute);
+app.post('/v1/webhooks/:id/test', testWebhookRoute);
+app.get('/v1/webhooks/:id', getWebhookRoute);
+app.put('/v1/webhooks/:id', updateWebhookRoute);
+app.delete('/v1/webhooks/:id', deleteWebhookRoute);
 // TAP Capability Attestation
 app.post('/v1/attestations', issueAttestationRoute);
 app.get('/v1/attestations/:id', getAttestationRoute);
@@ -1858,6 +2034,80 @@ app.post('/v1/verify/consumer', verifyConsumerRoute);
 app.post('/v1/verify/payment', verifyPaymentRoute);
 app.post('/v1/verify/delegation', verifyDelegationRoute);
 app.post('/v1/verify/attestation', verifyAttestationRoute);
+// ============ x402 PAYMENT GATING ENDPOINTS ============
+// HTTP 402 Payment Required protocol for agent micropayments.
+// Agents pay USDC on Base to receive BOTCHA tokens or access gated resources.
+// Info: x402 configuration discovery (public)
+app.get('/v1/x402/info', x402InfoRoute);
+// Challenge: pay $0.001 USDC → receive BOTCHA access_token (no puzzle required)
+// Without X-Payment header → 402 + payment requirements
+// With valid X-Payment header → 200 + { access_token, ... }
+app.get('/v1/x402/challenge', x402ChallengeRoute);
+// Facilitator: verify a raw x402 payment proof (utility endpoint)
+app.post('/v1/x402/verify-payment', x402VerifyPaymentRoute);
+// Webhook: receive payment settlement notifications from x402 facilitators
+app.post('/v1/x402/webhook', x402WebhookRoute);
+// Demo: BOTCHA token + x402 payment required (double-gated resource)
+app.get('/agent-only/x402', agentOnlyX402Route);
+// ============ ANS (AGENT NAME SERVICE) ENDPOINTS ============
+// BOTCHA as verification layer for the GoDaddy-led ANS standard.
+// ANS gives domain-level trust; BOTCHA adds behavior verification.
+// Reference: https://agentnameregistry.org
+//
+// NOTE: /v1/ans/discover and /v1/ans/botcha are public (no auth required).
+// /v1/ans/resolve/:name is public (DNS lookup, no sensitive data).
+// /v1/ans/verify requires app auth (issues signed credentials).
+// /v1/ans/nonce/:name requires app auth (nonce for ownership proof).
+// Public: BOTCHA's own ANS identity
+app.get('/v1/ans/botcha', getBotchaANSRoute);
+// Public: resolve any ANS name
+app.get('/v1/ans/resolve/lookup', resolveANSNameRoute);
+app.get('/v1/ans/resolve/:name', resolveANSNameRoute);
+// Public: discover BOTCHA-verified ANS agents
+app.get('/v1/ans/discover', discoverANSAgentsRoute);
+// Auth required: get a nonce for ownership verification
+app.get('/v1/ans/nonce/:name', getANSNonceRoute);
+app.get('/v1/ans/nonce', getANSNonceRoute);
+// Auth required: verify ANS ownership and issue badge
+app.post('/v1/ans/verify', verifyANSNameRoute);
+// ============ DID/VC (VERIFIABLE CREDENTIALS) ENDPOINTS ============
+// BOTCHA DID Document — public, no auth required
+app.get('/.well-known/did.json', didDocumentRoute);
+// VC Issuance — requires a valid BOTCHA access_token (from /v1/token/verify)
+app.post('/v1/credentials/issue', issueVCRoute);
+// VC Verification — public, no auth required (the VC JWT is the credential)
+app.post('/v1/credentials/verify', verifyVCRoute);
+// DID Resolution — public, resolves did:web DIDs
+app.get('/v1/dids/:did/resolve', resolveDIDRoute);
+// ============ A2A AGENT CARD ATTESTATION ============
+// BOTCHA as trust oracle for Google's A2A (Agent-to-Agent) protocol.
+// Agents discover BOTCHA via /.well-known/agent.json, then attest their
+// own cards via POST /v1/a2a/attest. Verifiers call POST /v1/a2a/verify-card.
+// BOTCHA's own A2A Agent Card (public discovery)
+app.get('/.well-known/agent.json', agentCardRoute);
+app.get('/v1/a2a/agent-card', agentCardRoute); // alias — same content at predictable /v1/ path
+// A2A attestation endpoints
+app.post('/v1/a2a/attest', attestCardRoute);
+app.post('/v1/a2a/verify-card', verifyCardRoute);
+app.post('/v1/a2a/verify-agent', verifyAgentRoute); // by card or agent_url shorthand
+app.get('/v1/a2a/trust-level/:agent_url', agentTrustLevelRoute);
+app.get('/v1/a2a/cards', listCardsRoute);
+app.get('/v1/a2a/cards/:id', getCardAttestationRoute);
+// ============ OIDC-A ATTESTATION (Epic 5) ============
+// Makes BOTCHA an agent_attestation endpoint in enterprise OIDC-A token chains.
+// Standards: draft-ietf-rats-eat-25, draft-aap-oauth-profile, RFC 8414, OIDC-A 1.0
+// OAuth 2.0 AS Discovery (RFC 8414) — no auth required, public
+app.get('/.well-known/oauth-authorization-server', oauthASMetadataRoute);
+// EAT (Entity Attestation Token) issuance — RFC 9334 / draft-ietf-rats-eat-25
+app.post('/v1/attestation/eat', issueEATRoute);
+// OIDC-A claims block — for embedding in enterprise ID tokens
+app.post('/v1/attestation/oidc-agent-claims', issueOIDCAgentClaimsRoute);
+// Agent Authorization Grant — draft-rosenberg-oauth-aauth
+app.post('/v1/auth/agent-grant', agentGrantRoute);
+app.get('/v1/auth/agent-grant/:id/status', agentGrantStatusRoute);
+app.post('/v1/auth/agent-grant/:id/resolve', agentGrantResolveRoute);
+// OIDC-A UserInfo endpoint
+app.get('/v1/oidc/userinfo', oidcUserInfoRoute);
 // ============ AGENT REGISTRY API ============
 // Register a new agent
 app.post('/v1/agents/register', async (c) => {
@@ -1945,6 +2195,26 @@ app.get('/v1/agents/:id', async (c) => {
         }, 500);
     }
 });
+// Delete an agent (requires Bearer token — must belong to the same app)
+app.delete('/v1/agents/:id', requireDashboardAuth, async (c) => {
+    try {
+        const agent_id = c.req.param('id');
+        if (!agent_id) {
+            return c.json({ success: false, error: 'MISSING_AGENT_ID', message: 'Agent ID is required' }, 400);
+        }
+        // requireDashboardAuth accepts both session cookie (browser) and Bearer token (agent)
+        const appId = c.get('dashboardAppId');
+        const result = await deleteAgent(c.env.AGENTS, agent_id, appId);
+        if (!result.success) {
+            const status = result.error === 'Agent not found' ? 404 : result.error === 'Agent does not belong to this app' ? 403 : 500;
+            return c.json({ success: false, error: result.error }, status);
+        }
+        return c.json({ success: true, agent_id, message: 'Agent deleted' });
+    }
+    catch (error) {
+        return c.json({ success: false, error: 'INTERNAL_ERROR', message: error instanceof Error ? error.message : 'Unknown error' }, 500);
+    }
+});
 // List all agents for an app
 app.get('/v1/agents', async (c) => {
     try {
@@ -1986,6 +2256,117 @@ app.post('/v1/auth/dashboard/verify', handleDashboardAuthVerify);
 // Device code flow (agent → human handoff)
 app.post('/v1/auth/device-code', handleDeviceCodeChallenge);
 app.post('/v1/auth/device-code/verify', handleDeviceCodeVerify);
+// ============ AGENT OAUTH APPROVAL PAGE ============
+app.get('/device', requireDashboardAuth, async (c) => {
+    const prefill = c.req.query('code') ?? '';
+    const appId = c.get('dashboardAppId') ?? '';
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>Authorize Agent — BOTCHA</title>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet"/>
+  <style>
+    *{box-sizing:border-box;margin:0;padding:0}
+    body{font-family:'JetBrains Mono',monospace;background:#fafafa;color:#111827;display:flex;align-items:center;justify-content:center;min-height:100vh;padding:24px}
+    .card{background:#fff;border:1px solid #e5e7eb;border-radius:4px;padding:40px;max-width:440px;width:100%}
+    h1{font-size:18px;font-weight:700;margin-bottom:6px}
+    p{font-size:13px;color:#6b7280;line-height:1.6;margin-bottom:20px}
+    input{width:100%;font-family:inherit;font-size:16px;font-weight:600;letter-spacing:0.1em;text-transform:uppercase;padding:12px 14px;border:1px solid #e5e7eb;border-radius:3px;background:#f9fafb;margin-bottom:16px;text-align:center}
+    input:focus{outline:none;border-color:#111827;background:#fff}
+    .btn{width:100%;font-family:inherit;font-size:12px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;padding:12px;border:none;border-radius:3px;cursor:pointer;transition:background 0.15s}
+    .btn-approve{background:#111827;color:#fff;margin-bottom:8px}
+    .btn-approve:hover{background:#374151}
+    .btn-deny{background:none;color:#9ca3af;border:1px solid #e5e7eb}
+    .btn-deny:hover{color:#ef4444;border-color:#fca5a5}
+    #status{font-size:13px;margin-top:16px;text-align:center;min-height:20px}
+    #agent-info{display:none;background:#f9fafb;border:1px solid #e5e7eb;border-radius:3px;padding:12px;margin-bottom:16px;font-size:12px;line-height:1.7;color:#374151}
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Authorize Agent</h1>
+    <p>Your agent is requesting permission to re-identify itself in future sessions without solving a new challenge each time.</p>
+    <div id="agent-info"></div>
+    <input id="code-input" type="text" placeholder="BOTCHA-XXXXXX" maxlength="13" value="${prefill}" oninput="this.value=this.value.toUpperCase();lookupCode(this.value)" />
+    <button class="btn btn-approve" onclick="approve()">Approve</button>
+    <button class="btn btn-deny" onclick="deny()">Deny</button>
+    <div id="status"></div>
+  </div>
+  <script>
+    var resolvedCode = null;
+    var lookupTimer = null;
+    function lookupCode(val) {
+      clearTimeout(lookupTimer);
+      if (val.length < 13) { document.getElementById('agent-info').style.display='none'; return; }
+      lookupTimer = setTimeout(async function() {
+        try {
+          const r = await fetch('/v1/oauth/lookup?user_code=' + encodeURIComponent(val));
+          const d = await r.json();
+          if (d.success) {
+            resolvedCode = val;
+            document.getElementById('agent-info').style.display = 'block';
+            document.getElementById('agent-info').innerHTML =
+              '<strong>Agent:</strong> ' + d.agent_id + '<br><strong>Name:</strong> ' + (d.name||'—') + '<br><strong>Operator:</strong> ' + (d.operator||'—');
+          }
+        } catch(e) {}
+      }, 400);
+    }
+    async function approve() { await submit('approve'); }
+    async function deny()    { await submit('deny'); }
+    async function submit(action) {
+      var code = document.getElementById('code-input').value.trim();
+      var status = document.getElementById('status');
+      if (!code) { status.textContent = 'Enter the code from your agent.'; return; }
+      status.textContent = action === 'approve' ? 'Approving…' : 'Denying…';
+      try {
+        const r = await fetch('/v1/oauth/approve', {
+          method:'POST', headers:{'Content-Type':'application/json'},
+          body: JSON.stringify({user_code: code, action})
+        });
+        const d = await r.json();
+        if (d.success) {
+          document.getElementById('code-input').disabled = true;
+          if (action === 'approve') {
+            status.innerHTML = '<strong style="color:#22c55e;">✓ Approved.</strong> Waiting for your agent to pick up the token…';
+            pollForPickup(document.getElementById('code-input').value);
+          } else {
+            status.innerHTML = '<strong style="color:#ef4444;">Denied.</strong> The agent was not authorized.';
+          }
+        } else {
+          status.textContent = 'Error: ' + (d.error || 'Unknown');
+        }
+      } catch(e) { status.textContent = 'Failed. Try again.'; }
+    }
+    function copyMsg(el) {
+      navigator.clipboard.writeText(el.textContent).then(function() {
+        document.getElementById('copy-hint').textContent = '✓ Copied';
+      });
+    }
+    var pickupTimer = null;
+    function pollForPickup(code) {
+      pickupTimer = setInterval(async function() {
+        try {
+          const r = await fetch('/v1/oauth/status?user_code=' + encodeURIComponent(code));
+          const d = await r.json();
+          if (d.status === 'consumed' || d.status === 'approved') {
+            clearInterval(pickupTimer);
+            document.getElementById('status').innerHTML =
+              '<strong style="color:#22c55e;">✓ Approved.</strong> Return to your agent and paste this:<br><br>' +
+              '<code id="paste-msg" style="display:block;background:#f3f4f6;border:1px solid #e5e7eb;border-radius:3px;padding:10px;font-size:12px;cursor:pointer;text-align:left;line-height:1.6;" onclick="copyMsg(this)">I approved the BOTCHA authorization. The user code was: ' + code + '</code>' +
+              '<span id="copy-hint" style="font-size:11px;color:#9ca3af;">click to copy</span>';
+          }
+        } catch(e) {}
+      }, 2000);
+    }
+    // Auto-lookup if prefilled
+    if (document.getElementById('code-input').value.length === 13) lookupCode(document.getElementById('code-input').value);
+  </script>
+</body>
+</html>`;
+    return c.html(html);
+});
 // ============ ONE-CLICK ACCESS LINKS ============
 /**
  * GET /go/:code - One-click device code redemption
@@ -2047,11 +2428,11 @@ app.get('/go/:code', async (c) => {
     const { redeemDeviceCode } = await import('./dashboard/device-code');
     const data = await redeemDeviceCode(c.env.CHALLENGES, normalizedCode);
     if (data) {
-        // Generate session token and redirect to dashboard
+        // Generate session token and redirect to account page
         const { generateSessionToken, setSessionCookie } = await import('./dashboard/auth');
         const sessionToken = await generateSessionToken(data.app_id, c.env.JWT_SECRET);
         setSessionCookie(c, sessionToken);
-        return c.redirect('/dashboard');
+        return c.redirect('/account');
     }
     // Neither code type found — redirect to landing with error
     return c.redirect('/?error=invalid');
@@ -2168,6 +2549,25 @@ app.post('/api/verify-landing', async (c) => {
         }
     });
 });
+// ============ 404 / ERROR HANDLERS ============
+// Return JSON 404 for unmatched routes (not 401 or plain-text)
+app.notFound((c) => {
+    return c.json({
+        success: false,
+        error: 'NOT_FOUND',
+        message: `Route ${c.req.method} ${c.req.path} not found`,
+        docs: 'https://botcha.ai',
+    }, 404);
+});
+// Catch-all error handler
+app.onError((err, c) => {
+    console.error('Unhandled error:', err);
+    return c.json({
+        success: false,
+        error: 'INTERNAL_ERROR',
+        message: 'An unexpected error occurred',
+    }, 500);
+});
 // ============ EXPORT ============
 export default app;
 // Also export utilities for use as a library