@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/index.js

@@ -15,41 +15,80 @@ 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 } 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();
-    c.header('X-Botcha-Version', c.env.BOTCHA_VERSION || '0.20.2');
+    c.header('X-Botcha-Version', c.env.BOTCHA_VERSION || '0.21.0');
     c.header('X-Botcha-Enabled', 'true');
     c.header('X-Botcha-Methods', 'speed-challenge,reasoning-challenge,hybrid-challenge,standard-challenge,jwt-token');
     c.header('X-Botcha-Docs', 'https://botcha.ai/openapi.json');
     c.header('X-Botcha-Runtime', 'cloudflare-workers');
 });
-// Rate limiting middleware for challenge generation
+app.use('/v1/*', async (c, next) => {
+    const path = new URL(c.req.url).pathname;
+    // Allow open paths through without app_id
+    if (shouldBypassAppGate(path, c.req.method)) {
+        return next();
+    }
+    // Also allow GET /v1/apps/:id (app info lookup)
+    if (/^\/v1\/apps\/[^/]+$/.test(path) && c.req.method === 'GET') {
+        return next();
+    }
+    return requireAppId(c, next);
+});
+// Rate limiting middleware for challenge generation (app-scoped when app_id present)
 async function rateLimitMiddleware(c, next) {
     const clientIP = getClientIP(c.req.raw);
-    const rateLimitResult = await checkRateLimit(c.env.RATE_LIMITS, clientIP, 100);
+    const appId = c.req.query('app_id') || c.req.header('x-app-id');
+    const rateLimitResult = await checkRateLimit(c.env.RATE_LIMITS, clientIP, 100, appId);
     // Add rate limit headers
     c.header('X-RateLimit-Limit', '100');
     c.header('X-RateLimit-Remaining', rateLimitResult.remaining.toString());
@@ -68,20 +107,21 @@ async function rateLimitMiddleware(c, next) {
     await next();
 }
 // Helper: Validate app_id against APPS KV (fail-open)
+// Note: The requireAppId middleware handles the "must have app_id" check globally.
+// This helper does additional route-level validation (e.g., consistency checks).
 async function validateAppId(appId, appsKV) {
     if (!appId) {
-        // No app_id provided - valid (not required)
-        return { valid: true };
+        return {
+            valid: false,
+            error: 'app_id is required. Register at POST https://botcha.ai/v1/apps with {"email": "you@example.com"}.',
+        };
     }
     try {
         const app = await getApp(appsKV, appId);
         if (!app) {
             return {
                 valid: false,
-                error: `App not found: ${appId}. ` +
-                    `app_id is OPTIONAL — remove it to get a token without an app. ` +
-                    `To register an app: POST https://botcha.ai/v1/apps with {"email": "you@example.com", "name": "My App"}. ` +
-                    `App IDs look like: app_a1b2c3d4e5f6a7b8`
+                error: `App not found: ${appId}. Register at POST https://botcha.ai/v1/apps with {"email": "you@example.com"}.`,
             };
         }
         return { valid: true };
@@ -92,6 +132,91 @@ async function validateAppId(appId, appsKV) {
         return { valid: true };
     }
 }
+// ============ APP GATE MIDDLEWARE ============
+// Requires a registered app_id with verified email on all gated /v1/* routes.
+// Extracts app_id from: query param, X-App-Id header, request body, or JWT Bearer token claim.
+async function requireAppId(c, next) {
+    // 1. Extract app_id from multiple sources
+    const queryAppId = c.req.query('app_id');
+    const headerAppId = c.req.header('x-app-id');
+    // Try request body for POST/PUT requests (e.g., /v1/token/verify sends app_id in body)
+    let bodyAppId;
+    if (c.req.method === 'POST' || c.req.method === 'PUT') {
+        try {
+            const body = await c.req.json();
+            if (body && typeof body.app_id === 'string') {
+                bodyAppId = body.app_id;
+            }
+        }
+        catch {
+            // Body not JSON or not parseable — that's fine
+        }
+    }
+    // Try JWT claim if Bearer token present
+    let jwtAppId;
+    const authHeader = c.req.header('authorization');
+    const token = extractBearerToken(authHeader);
+    if (token) {
+        try {
+            const publicKey = getPublicKey(c.env);
+            const result = await verifyToken(token, c.env.JWT_SECRET, c.env, undefined, publicKey);
+            if (result.valid && result.payload?.app_id) {
+                jwtAppId = result.payload.app_id;
+            }
+        }
+        catch {
+            // Token invalid — will be caught by route-level auth if needed
+        }
+    }
+    const appId = queryAppId || headerAppId || bodyAppId || jwtAppId;
+    // 2. No app_id at all → 401 with registration instructions
+    if (!appId) {
+        return c.json({
+            success: false,
+            error: 'APP_REGISTRATION_REQUIRED',
+            message: 'All API endpoints require a registered app. Create one for free:',
+            registration: {
+                endpoint: 'POST https://botcha.ai/v1/apps',
+                body: '{"email": "you@example.com", "name": "My App"}',
+                note: 'You will receive a 6-digit verification code via email. Verify to activate your app.',
+            },
+            docs: 'https://botcha.ai/ai.txt',
+        }, 401);
+    }
+    // 3. Validate app exists and email is verified
+    try {
+        const app = await getApp(c.env.APPS, appId);
+        if (!app) {
+            return c.json({
+                success: false,
+                error: 'APP_NOT_FOUND',
+                message: `App '${appId}' not found. Register at POST https://botcha.ai/v1/apps`,
+            }, 401);
+        }
+        if (!app.email_verified) {
+            return c.json({
+                success: false,
+                error: 'EMAIL_NOT_VERIFIED',
+                message: 'Your app email must be verified before using the API.',
+                next_step: `POST https://botcha.ai/v1/apps/${appId}/verify-email with {"code": "<6-digit code>", "app_secret": "<your_secret>"}`,
+                resend: `POST https://botcha.ai/v1/apps/${appId}/resend-verification`,
+            }, 403);
+        }
+    }
+    catch (error) {
+        // Fail-open on KV errors — log warning and proceed
+        console.warn(`requireAppId: KV lookup failed for ${appId}, proceeding (fail-open):`, error);
+    }
+    // 4. Cross-check: if both query and JWT have app_id, they must match
+    if (queryAppId && jwtAppId && queryAppId !== jwtAppId) {
+        return c.json({
+            success: false,
+            error: 'APP_ID_MISMATCH',
+            message: `Query app_id '${queryAppId}' does not match token app_id '${jwtAppId}'.`,
+        }, 400);
+    }
+    await next();
+}
 // Helper: Parse ES256 signing key from env, returning undefined if not set
 function getSigningKey(env) {
     if (!env.JWT_SIGNING_KEY)
@@ -186,6 +311,44 @@ async function resolveAuthenticatedAppId(c) {
         status: 200,
     };
 }
+// Authorize app management actions using either app_secret or a dashboard session token.
+async function authorizeAppManagement(c, appId, appSecretFromBody) {
+    const headerAppSecret = c.req.header('x-app-secret');
+    const appSecret = appSecretFromBody?.trim() || headerAppSecret?.trim();
+    // App-secret proof (works immediately after app creation and outside dashboard).
+    if (appSecret) {
+        const valid = await validateAppSecret(c.env.APPS, appId, appSecret);
+        if (valid) {
+            return { authorized: true, status: 200 };
+        }
+    }
+    // Dashboard session proof (Bearer token or cookie).
+    const authHeader = c.req.header('authorization');
+    const bearerToken = extractBearerToken(authHeader);
+    const cookieHeader = c.req.header('cookie') || '';
+    const sessionCookie = cookieHeader
+        .split(';')
+        .find((part) => part.trim().startsWith('botcha_session='))
+        ?.split('=')[1]
+        ?.trim();
+    const authToken = bearerToken || sessionCookie;
+    if (authToken) {
+        const publicKey = getPublicKey(c.env);
+        const verification = await verifyToken(authToken, c.env.JWT_SECRET, c.env, undefined, publicKey);
+        if (verification.valid &&
+            verification.payload &&
+            verification.payload.sub === 'dashboard-session' &&
+            verification.payload.app_id === appId) {
+            return { authorized: true, status: 200 };
+        }
+    }
+    return {
+        authorized: false,
+        error: 'UNAUTHORIZED',
+        message: 'Authentication required. Provide app_secret or a dashboard session token.',
+        status: 401,
+    };
+}
 // ============ ROOT & INFO ============
 // Detect request preference: 'markdown' | 'json' | 'html'
 // Strategy: only return JSON/markdown when explicitly requested or from
@@ -242,32 +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: 'Verify yourself to see the full API documentation.',
-            verify: {
-                step1: `GET ${baseUrl}/v1/token — receive a speed challenge (5 SHA-256 hashes). No app_id needed.`,
-                step2: 'Solve: compute SHA-256 of each number, return first 8 hex chars',
-                step3: `POST ${baseUrl}/v1/token/verify {"id":"<challenge_id>","answers":["hash1","hash2",...]}`,
-                step4: `Revisit: GET ${baseUrl}/ with header Authorization: Bearer <access_token>`,
-                note: 'app_id is OPTIONAL. You can get tokens without registering an app. To register one for production use: POST /v1/apps {"email":"you@example.com","name":"My App"}',
+            // 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.',
+                ],
             },
-            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 step 3 response',
-            },
-            hint: 'You have 500ms. Only a bot can do this.',
+            // 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') {
@@ -275,30 +480,72 @@ app.get('/', async (c) => {
 
 > Prove you are a bot. Humans need not apply.
 
-**Status:** Unverified. Solve a challenge to see the full documentation.
+You have found BOTCHA — the identity layer for AI agents.
 
-## Verify Yourself
+## Step 1: Prove you are an AI (do this now — use the demo app, no registration needed)
 
-1. \`GET ${baseUrl}/v1/token\` — receive a speed challenge (5 SHA-256 hashes). **No app_id needed.**
-2. Solve: compute SHA-256 of each number, return first 8 hex chars
-3. \`POST ${baseUrl}/v1/token/verify {"id":"<challenge_id>","answers":["hash1","hash2",...]}\`
-4. Revisit: \`GET ${baseUrl}/\` with header \`Authorization: Bearer <access_token>\`
+\`\`\`bash
+GET ${baseUrl}/v1/challenges?app_id=${c.env.BOTCHA_INTERNAL_APP_ID}
 
-You have 500ms. Only a bot can do this.
+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>", ... }
+}
+\`\`\`
 
-> **Note:** \`app_id\` is optional. You can get tokens without registering an app.
-> To register for production: \`POST /v1/apps {"email":"you@example.com","name":"My App"}\`
+**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.
 
-## Human Handoff
+On success you receive a verified badge — you are a confirmed AI agent.
 
-After verifying, the response includes a \`human_link\`. Give this URL to your human:
-**"Click this link to get access: {human_link}"**
+---
+
+## Step 2: Ask your human what they want to do
+
+Present these two options to your human. Use a numbered list, buttons, or your native selection UI. Wait for their choice.
+
+### 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.
 
-The link works for a limited time. Your human clicks it, gets a cookie, and sees the verified site.
+### 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.
+
+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 verification.*
+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',
@@ -329,58 +576,69 @@ The link works for a limited time. Your human clicks it, gets a cookie, and sees
             audience: tokenPayload?.aud || null,
             solve_time_ms: tokenPayload?.solveTime,
         },
+        // === APP REGISTRATION REQUIRED (v0.21.0) ===
+        registration_required: {
+            note: 'All /v1/* API endpoints require a registered app with verified email.',
+            demo: 'The homepage demo at botcha.ai lets agents try challenges without registering.',
+            how_to_provide: 'Provide app_id via ?app_id=, X-App-Id header, or JWT claim',
+        },
         // === FULL SETUP: register your app and agent identity ===
         onboarding: {
             note: 'For production use. Creates your app, verifies your human, registers your identity.',
             steps: [
                 '1. Ask your human operator for their email address.',
-                `2. POST ${baseUrl}/v1/apps {"email":"human@example.com","name":"My App"} — returns app_id + name + app_secret (shown ONCE).`,
+                `2. POST ${baseUrl}/v1/apps {"email":"human@example.com","name":"My App"} — returns app_id + name + app_secret (shown ONCE). NO app_id needed.`,
                 '3. Human receives a 6-digit verification code via email — ask them for it.',
-                `4. POST ${baseUrl}/v1/apps/{app_id}/verify-email {"code":"123456"} — enables account recovery.`,
-                `5. Register yourself: POST ${baseUrl}/v1/agents/register {"name":"my-agent","operator":"my-org"} — persistent agent identity.`,
-                `6. Solve challenges with your app: GET ${baseUrl}/v1/challenges?app_id=...`,
-                `7. Dashboard for your human: POST ${baseUrl}/v1/auth/device-code {"app_id":"..."}, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code.`,
-                `8. Lost your secret? POST ${baseUrl}/v1/auth/recover {"email":"..."} — recovery code emailed.`,
+                `4. POST ${baseUrl}/v1/apps/{app_id}/verify-email {"code":"123456","app_secret":"sk_..."} — enables account recovery. NO app_id needed.`,
+                `5. Use your app_id on ALL other /v1/* endpoints via ?app_id=, X-App-Id header, or JWT claim.`,
+                `6. Register yourself: POST ${baseUrl}/v1/agents/register {"name":"my-agent","operator":"my-org"} — persistent agent identity (requires app_id).`,
+                `7. Solve challenges with your app: GET ${baseUrl}/v1/challenges?app_id=... (requires app_id)`,
+                `8. Dashboard for your human: POST ${baseUrl}/v1/auth/device-code {"app_id":"..."}, solve challenge, give human the BOTCHA-XXXX code for /dashboard/code (requires app_id).`,
+                `9. Lost your secret? POST ${baseUrl}/v1/auth/recover {"email":"..."} — recovery code emailed (no app_id needed).`,
             ],
         },
         // === All endpoints, grouped by domain ===
         endpoints: {
             challenges: {
-                'GET /v1/challenges': 'Get a challenge (hybrid by default, no auth required)',
-                'GET /v1/challenges?type=speed': 'Speed-only (SHA256 in <500ms)',
-                'GET /v1/challenges?type=standard': 'Standard puzzle challenge',
-                'POST /v1/challenges/:id/verify': 'Verify challenge solution',
+                note: 'All challenge endpoints require app_id',
+                'GET /v1/challenges': 'Get a challenge (hybrid by default) — app_id required',
+                'GET /v1/challenges?type=speed': 'Speed-only (SHA256 in <500ms) — app_id required',
+                'GET /v1/challenges?type=standard': 'Standard puzzle challenge — app_id required',
+                'POST /v1/challenges/:id/verify': 'Verify challenge solution — app_id required',
             },
             tokens: {
-                note: 'Use token flow when you need a Bearer token for protected endpoints.',
-                'GET /v1/token': 'Get speed challenge for token flow (?audience= optional)',
-                'POST /v1/token/verify': 'Submit solution → access_token (1hr) + refresh_token (1hr)',
-                'POST /v1/token/refresh': 'Refresh access token',
-                'POST /v1/token/revoke': 'Revoke a token',
-                'POST /v1/token/validate': 'Remote token validation — verify any BOTCHA token without needing the secret',
+                note: 'All token endpoints require app_id. Use token flow when you need a Bearer token for protected endpoints.',
+                'GET /v1/token': 'Get speed challenge for token flow (?audience= optional) — app_id required',
+                '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. Public endpoint — the token itself is the credential, no app_id required.',
             },
             protected: {
-                'GET /agent-only': 'Demo protected endpoint — requires Bearer token',
+                'GET /agent-only': 'Demo protected endpoint — requires Bearer token (app_id required)',
                 'GET /': 'This documentation (requires Bearer token for full version)',
             },
             apps: {
-                note: 'Create an app for isolated rate limits, scoped tokens, and dashboard access.',
-                '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/rotate-secret': 'Rotate app secret (auth required)',
+                note: 'App management endpoints. Registration and verification do NOT require app_id.',
+                'POST /v1/apps': 'Create app (email required, name optional) → app_id + name + app_secret — NO app_id required',
+                'GET /v1/apps/:id': 'Get app info — NO app_id required',
+                'POST /v1/apps/:id/verify-email': 'Verify email with 6-digit code (app_secret auth required) — NO app_id required',
+                'POST /v1/apps/:id/resend-verification': 'Resend verification email (app_secret auth required) — NO app_id required',
+                'POST /v1/apps/:id/rotate-secret': 'Rotate app secret (auth required) — app_id required',
             },
             agents: {
-                note: 'Register a persistent identity for your agent.',
-                'POST /v1/agents/register': 'Register agent identity (name, operator, version)',
-                'GET /v1/agents/:id': 'Get agent by ID (public, no auth)',
-                'GET /v1/agents': 'List all agents for your app (auth required)',
+                note: 'All agent endpoints require app_id. Register a persistent identity for your agent.',
+                'POST /v1/agents/register': 'Register agent identity (name, operator, version) — app_id required',
+                'GET /v1/agents/:id': 'Get agent by ID (public, no auth) — app_id required',
+                'GET /v1/agents': 'List all agents for your app (auth required) — app_id required',
             },
             recovery: {
-                'POST /v1/auth/recover': 'Account recovery via verified email',
+                note: 'Recovery does NOT require app_id',
+                'POST /v1/auth/recover': 'Account recovery via verified email — NO app_id required',
             },
             dashboard: {
-                'POST /v1/auth/device-code': 'Get challenge for device code flow',
+                note: 'Dashboard endpoints require app_id',
+                'POST /v1/auth/device-code': 'Get challenge for device code flow — app_id required',
                 'GET /dashboard': 'Metrics dashboard (login required)',
             },
         },
@@ -403,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',
@@ -525,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, {
@@ -816,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,
@@ -912,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,
@@ -1427,15 +1720,12 @@ app.post('/v1/apps', async (c) => {
             }, 400);
         }
         const result = await createApp(c.env.APPS, email, trimmedName || undefined);
-        // Generate a fresh verification code and send email
-        const regen = await regenerateVerificationCode(c.env.APPS, result.app_id);
-        if (regen) {
-            const template = verificationEmail(regen.code);
-            await sendEmail(c.env.RESEND_API_KEY, {
-                ...template,
-                to: email,
-            });
-        }
+        // Send verification email with the code returned from createApp
+        const template = verificationEmail(result.verification_code);
+        await sendEmail(c.env.RESEND_API_KEY, {
+            ...template,
+            to: email,
+        });
         return c.json({
             success: true,
             app_id: result.app_id,
@@ -1444,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" }`,
+            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',
@@ -1492,7 +1792,7 @@ app.get('/v1/apps/:id', async (c) => {
 app.post('/v1/apps/:id/verify-email', async (c) => {
     const app_id = c.req.param('id');
     const body = await c.req.json().catch(() => ({}));
-    const { code } = body;
+    const { code, app_secret } = body;
     if (!code || typeof code !== 'string') {
         return c.json({
             success: false,
@@ -1500,6 +1800,14 @@ app.post('/v1/apps/:id/verify-email', async (c) => {
             message: 'Provide { "code": "123456" } in the request body',
         }, 400);
     }
+    const auth = await authorizeAppManagement(c, app_id, app_secret);
+    if (!auth.authorized) {
+        return c.json({
+            success: false,
+            error: auth.error,
+            message: auth.message,
+        }, auth.status);
+    }
     const result = await verifyEmailCode(c.env.APPS, app_id, code);
     if (!result.verified) {
         return c.json({
@@ -1517,6 +1825,15 @@ app.post('/v1/apps/:id/verify-email', async (c) => {
 // Resend verification email
 app.post('/v1/apps/:id/resend-verification', async (c) => {
     const app_id = c.req.param('id');
+    const body = await c.req.json().catch(() => ({}));
+    const auth = await authorizeAppManagement(c, app_id, body.app_secret);
+    if (!auth.authorized) {
+        return c.json({
+            success: false,
+            error: auth.error,
+            message: auth.message,
+        }, auth.status);
+    }
     const appData = await getApp(c.env.APPS, app_id);
     if (!appData) {
         return c.json({ success: false, error: 'App not found' }, 404);
@@ -1648,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
@@ -1666,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);
@@ -1681,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) => {
@@ -1768,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 {
@@ -1809,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
@@ -1870,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');
@@ -1991,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