@dupecom/botcha-cloudflare 0.3.2 → 0.9.0

package/dist/index.js

@@ -7,11 +7,14 @@
  */
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
-import { generateSpeedChallenge, verifySpeedChallenge, generateStandardChallenge, verifyStandardChallenge, generateReasoningChallenge, verifyReasoningChallenge, generateHybridChallenge, verifyHybridChallenge, verifyLandingChallenge, } from './challenges';
-import { generateToken, verifyToken, extractBearerToken } from './auth';
+import { generateSpeedChallenge, verifySpeedChallenge, generateStandardChallenge, verifyStandardChallenge, generateReasoningChallenge, verifyReasoningChallenge, generateHybridChallenge, verifyHybridChallenge, verifyLandingChallenge, validateLandingToken, } from './challenges';
+import { generateToken, verifyToken, extractBearerToken, revokeToken, refreshAccessToken } from './auth';
 import { checkRateLimit, getClientIP } from './rate-limit';
 import { verifyBadge, generateBadgeSvg, generateBadgeHtml, createBadgeResponse } from './badge';
 import streamRoutes from './routes/stream';
+import { ROBOTS_TXT, AI_TXT, AI_PLUGIN_JSON, SITEMAP_XML, getOpenApiSpec } from './static';
+import { createApp, getApp } from './apps';
+import { trackChallengeGenerated, trackChallengeVerified, trackAuthAttempt, trackRateLimitExceeded, } from './analytics';
 const app = new Hono();
 // ============ MIDDLEWARE ============
 app.use('*', cors());
@@ -36,6 +39,8 @@ async function rateLimitMiddleware(c, next) {
     c.header('X-RateLimit-Reset', new Date(rateLimitResult.resetAt).toISOString());
     if (!rateLimitResult.allowed) {
         c.header('Retry-After', rateLimitResult.retryAfter?.toString() || '3600');
+        // Track rate limit exceeded
+        await trackRateLimitExceeded(c.env.ANALYTICS, c.req.path, c.req.raw, clientIP);
         return c.json({
             error: 'RATE_LIMIT_EXCEEDED',
             message: 'You have exceeded the rate limit. Free tier: 100 challenges/hour/IP',
@@ -45,6 +50,25 @@ async function rateLimitMiddleware(c, next) {
     }
     await next();
 }
+// Helper: Validate app_id against APPS KV (fail-open)
+async function validateAppId(appId, appsKV) {
+    if (!appId) {
+        // No app_id provided - valid (not required)
+        return { valid: true };
+    }
+    try {
+        const app = await getApp(appsKV, appId);
+        if (!app) {
+            return { valid: false, error: `App not found: ${appId}` };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        // Fail-open: if KV is unavailable, log warning and proceed
+        console.warn(`Failed to validate app_id ${appId} (KV unavailable), proceeding:`, error);
+        return { valid: true };
+    }
+}
 // JWT verification middleware
 async function requireJWT(c, next) {
     const authHeader = c.req.header('authorization');
@@ -55,7 +79,7 @@ async function requireJWT(c, next) {
             message: 'Missing Bearer token. Use POST /v1/token/verify to get a token.',
         }, 401);
     }
-    const result = await verifyToken(token, c.env.JWT_SECRET);
+    const result = await verifyToken(token, c.env.JWT_SECRET, c.env);
     if (!result.valid) {
         return c.json({
             error: 'INVALID_TOKEN',
@@ -128,6 +152,7 @@ function getHumanLanding(version) {
 ║  Or install the SDK:                                         ║
 ║                                                              ║
 ║    npm install @dupecom/botcha                               ║
+║    pip install botcha                                        ║
 ║                                                              ║
 ║  GitHub:  https://github.com/dupe-com/botcha                 ║
 ║  npm:     https://npmjs.com/package/@dupecom/botcha          ║
@@ -154,10 +179,11 @@ app.get('/', (c) => {
         description: 'BOTCHA is a reverse CAPTCHA - computational challenges that only AI agents can solve. Use it to protect your APIs from humans and verify bot authenticity.',
         quickstart: {
             step1: 'GET /v1/challenges to receive a challenge',
-            step2: 'Solve the SHA256 hash problems within 500ms',
+            step2: 'Solve the SHA256 hash problems within allocated time',
             step3: 'POST your answers to verify',
             step4: 'Receive a JWT token for authenticated access',
             example: 'curl https://botcha.ai/v1/challenges',
+            rttAware: 'curl "https://botcha.ai/v1/challenges?type=speed&ts=$(date +%s000)"',
         },
         endpoints: {
             challenges: {
@@ -177,10 +203,16 @@ app.get('/', (c) => {
                 'POST /v1/challenge/stream/:session': 'Send actions to streaming session',
             },
             authentication: {
-                'GET /v1/token': 'Get challenge for JWT token flow',
-                'POST /v1/token/verify': 'Verify challenge and receive JWT token',
+                'GET /v1/token': 'Get challenge for JWT token flow (supports ?audience= param)',
+                'POST /v1/token/verify': 'Verify challenge and receive JWT tokens (access + refresh)',
+                'POST /v1/token/refresh': 'Refresh access token using refresh token',
+                'POST /v1/token/revoke': 'Revoke a token (access or refresh)',
                 'GET /agent-only': 'Protected endpoint (requires Bearer token)',
             },
+            apps: {
+                'POST /v1/apps': 'Create a new app with app_id and app_secret (multi-tenant)',
+                'GET /v1/apps/:id': 'Get app information by app_id (without secret)',
+            },
             badges: {
                 'GET /badge/:id': 'Badge verification page (HTML)',
                 'GET /badge/:id/image': 'Badge image (SVG)',
@@ -193,9 +225,11 @@ app.get('/', (c) => {
         },
         challengeTypes: {
             speed: {
-                description: 'Compute SHA256 hashes of 5 numbers in under 500ms',
+                description: 'Compute SHA256 hashes of 5 numbers with RTT-aware timeout',
                 difficulty: 'Only bots can solve this fast enough',
-                timeLimit: '500ms',
+                timeLimit: '500ms base + network latency compensation',
+                rttAware: 'Include ?ts=<timestamp> for fair timeout adjustment',
+                formula: 'timeout = 500ms + (2 × RTT) + 100ms buffer',
             },
             reasoning: {
                 description: 'Answer 3 questions requiring AI reasoning capabilities',
@@ -205,19 +239,34 @@ app.get('/', (c) => {
             hybrid: {
                 description: 'Combines speed AND reasoning challenges',
                 difficulty: 'The ultimate bot verification',
-                timeLimit: 'Speed: 500ms, Reasoning: 30s',
+                timeLimit: 'Speed: RTT-aware, Reasoning: 30s',
+                rttAware: 'Speed component automatically adjusts for network latency',
             },
         },
         authentication: {
             flow: [
-                '1. GET /v1/token - receive challenge',
+                '1. GET /v1/token?audience=myapi - receive challenge (optional audience param)',
                 '2. Solve the challenge',
-                '3. POST /v1/token/verify - submit solution',
-                '4. Receive JWT token (valid 1 hour)',
-                '5. Use: Authorization: Bearer <token>',
+                '3. POST /v1/token/verify - submit solution with optional audience and bind_ip',
+                '4. Receive access_token (5 min) and refresh_token (1 hour)',
+                '5. Use: Authorization: Bearer <access_token>',
+                '6. Refresh: POST /v1/token/refresh with refresh_token',
+                '7. Revoke: POST /v1/token/revoke with token',
             ],
-            tokenExpiry: '1 hour',
-            usage: 'Authorization: Bearer <token>',
+            tokens: {
+                access_token: '5 minutes (for API access)',
+                refresh_token: '1 hour (to get new access tokens)',
+            },
+            usage: 'Authorization: Bearer <access_token>',
+            features: ['audience claims', 'client IP binding', 'token revocation', 'refresh tokens'],
+        },
+        rttAwareness: {
+            purpose: 'Fair challenges for agents on slow networks',
+            usage: 'Include client timestamp in ?ts=<timestamp_ms> or X-Client-Timestamp header',
+            formula: 'timeout = 500ms + (2 × RTT) + 100ms buffer',
+            example: '/v1/challenges?type=speed&ts=1770722465000',
+            benefit: 'Agents worldwide get fair treatment regardless of network speed',
+            security: 'Humans still cannot solve challenges even with extra time',
         },
         rateLimit: {
             free: '100 challenges/hour/IP',
@@ -225,12 +274,16 @@ app.get('/', (c) => {
         },
         sdk: {
             npm: 'npm install @dupecom/botcha',
+            python: 'pip install botcha',
             cloudflare: 'npm install @dupecom/botcha-cloudflare',
+            verify_ts: 'npm install @botcha/verify',
+            verify_python: 'pip install botcha-verify',
             usage: "import { BotchaClient } from '@dupecom/botcha/client'",
         },
         links: {
             github: 'https://github.com/dupe-com/botcha',
             npm: 'https://www.npmjs.com/package/@dupecom/botcha',
+            pypi: 'https://pypi.org/project/botcha',
             npmCloudflare: 'https://www.npmjs.com/package/@dupecom/botcha-cloudflare',
             openapi: 'https://botcha.ai/openapi.json',
             aiPlugin: 'https://botcha.ai/.well-known/ai-plugin.json',
@@ -245,17 +298,76 @@ app.get('/', (c) => {
 app.get('/health', (c) => {
     return c.json({ status: 'ok', runtime: 'cloudflare-workers' });
 });
+// ============ STATIC DISCOVERY FILES ============
+// robots.txt - AI crawler instructions
+app.get('/robots.txt', (c) => {
+    return c.text(ROBOTS_TXT, 200, {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'public, max-age=86400',
+    });
+});
+// ai.txt - AI agent discovery file
+app.get('/ai.txt', (c) => {
+    return c.text(AI_TXT, 200, {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'public, max-age=86400',
+    });
+});
+// OpenAPI spec
+app.get('/openapi.json', (c) => {
+    const version = c.env.BOTCHA_VERSION || '0.3.0';
+    return c.json(getOpenApiSpec(version), 200, {
+        'Cache-Control': 'public, max-age=3600',
+    });
+});
+// AI plugin manifest (ChatGPT/OpenAI format)
+app.get('/.well-known/ai-plugin.json', (c) => {
+    return c.json(AI_PLUGIN_JSON, 200, {
+        'Cache-Control': 'public, max-age=86400',
+    });
+});
+// Sitemap
+app.get('/sitemap.xml', (c) => {
+    return c.body(SITEMAP_XML, 200, {
+        'Content-Type': 'application/xml; charset=utf-8',
+        'Cache-Control': 'public, max-age=86400',
+    });
+});
 // ============ V1 API ============
 // Generate challenge (hybrid by default, also supports speed and standard)
 app.get('/v1/challenges', rateLimitMiddleware, async (c) => {
+    const startTime = Date.now();
     const type = c.req.query('type') || 'hybrid';
     const difficulty = c.req.query('difficulty') || 'medium';
+    // Extract client timestamp for RTT calculation
+    const clientTimestampParam = c.req.query('ts') || c.req.header('x-client-timestamp');
+    const clientTimestamp = clientTimestampParam ? parseInt(clientTimestampParam, 10) : undefined;
+    // Extract and validate optional app_id
+    const app_id = c.req.query('app_id');
+    if (app_id) {
+        const validation = await validateAppId(app_id, c.env.APPS);
+        if (!validation.valid) {
+            return c.json({
+                success: false,
+                error: 'INVALID_APP_ID',
+                message: validation.error || 'Invalid app_id',
+            }, 400);
+        }
+    }
+    const baseUrl = new URL(c.req.url).origin;
+    const clientIP = getClientIP(c.req.raw);
     if (type === 'hybrid') {
-        const challenge = await generateHybridChallenge(c.env.CHALLENGES);
-        return c.json({
+        const challenge = await generateHybridChallenge(c.env.CHALLENGES, clientTimestamp, app_id);
+        // Track challenge generation
+        const responseTime = Date.now() - startTime;
+        await trackChallengeGenerated(c.env.ANALYTICS, 'hybrid', '/v1/challenges', c.req.raw, clientIP, responseTime);
+        const warning = challenge.rttInfo
+            ? `🔥 HYBRID CHALLENGE: Solve speed problems in <${challenge.speed.timeLimit}ms (RTT-adjusted) AND answer reasoning questions!`
+            : '🔥 HYBRID CHALLENGE: Solve speed problems in <500ms AND answer reasoning questions!';
+        const response = {
             success: true,
             type: 'hybrid',
-            warning: '🔥 HYBRID CHALLENGE: Solve speed problems in <500ms AND answer reasoning questions!',
+            warning,
             challenge: {
                 id: challenge.id,
                 speed: {
@@ -271,11 +383,25 @@ app.get('/v1/challenges', rateLimitMiddleware, async (c) => {
             },
             instructions: challenge.instructions,
             tip: '🔥 This is the ultimate test: proves you can compute AND reason like an AI.',
-        });
+            verify_endpoint: `${baseUrl}/v1/challenges/${challenge.id}/verify`,
+            submit_body: {
+                type: 'hybrid',
+                speed_answers: ['hash1', 'hash2', '...'],
+                reasoning_answers: { 'question-id': 'answer', '...': '...' }
+            }
+        };
+        // Include RTT info if available
+        if (challenge.rttInfo) {
+            response.rtt_adjustment = challenge.rttInfo;
+        }
+        return c.json(response);
     }
     else if (type === 'speed') {
-        const challenge = await generateSpeedChallenge(c.env.CHALLENGES);
-        return c.json({
+        const challenge = await generateSpeedChallenge(c.env.CHALLENGES, clientTimestamp, app_id);
+        // Track challenge generation
+        const responseTime = Date.now() - startTime;
+        await trackChallengeGenerated(c.env.ANALYTICS, 'speed', '/v1/challenges', c.req.raw, clientIP, responseTime);
+        const response = {
             success: true,
             type: 'speed',
             challenge: {
@@ -284,11 +410,26 @@ app.get('/v1/challenges', rateLimitMiddleware, async (c) => {
                 timeLimit: `${challenge.timeLimit}ms`,
                 instructions: challenge.instructions,
             },
-            tip: '⚡ Speed challenge: You have 500ms to solve ALL problems. Humans cannot copy-paste fast enough.',
-        });
+            tip: challenge.rttInfo
+                ? `⚡ RTT-adjusted speed challenge: ${challenge.rttInfo.explanation}. Humans still can't copy-paste fast enough!`
+                : '⚡ Speed challenge: You have 500ms to solve ALL problems. Humans cannot copy-paste fast enough.',
+            verify_endpoint: `${baseUrl}/v1/challenges/${challenge.id}/verify`,
+            submit_body: {
+                type: 'speed',
+                answers: ['hash1', 'hash2', 'hash3', 'hash4', 'hash5']
+            }
+        };
+        // Include RTT info if available
+        if (challenge.rttInfo) {
+            response.rtt_adjustment = challenge.rttInfo;
+        }
+        return c.json(response);
     }
     else {
-        const challenge = await generateStandardChallenge(difficulty, c.env.CHALLENGES);
+        const challenge = await generateStandardChallenge(difficulty, c.env.CHALLENGES, app_id);
+        // Track challenge generation
+        const responseTime = Date.now() - startTime;
+        await trackChallengeGenerated(c.env.ANALYTICS, 'standard', '/v1/challenges', c.req.raw, clientIP, responseTime);
         return c.json({
             success: true,
             type: 'standard',
@@ -298,12 +439,17 @@ app.get('/v1/challenges', rateLimitMiddleware, async (c) => {
                 timeLimit: `${challenge.timeLimit}ms`,
                 hint: challenge.hint,
             },
+            verify_endpoint: `${baseUrl}/v1/challenges/${challenge.id}/verify`,
+            submit_body: {
+                answer: 'your-answer'
+            }
         });
     }
 });
 // Verify challenge (supports hybrid, speed, and standard)
 app.post('/v1/challenges/:id/verify', async (c) => {
     const id = c.req.param('id');
+    const clientIP = getClientIP(c.req.raw);
     const body = await c.req.json();
     const { answers, answer, type, speed_answers, reasoning_answers } = body;
     // Hybrid challenge (default)
@@ -315,6 +461,8 @@ app.post('/v1/challenges/:id/verify', async (c) => {
             }, 400);
         }
         const result = await verifyHybridChallenge(id, speed_answers, reasoning_answers, c.env.CHALLENGES);
+        // Track verification
+        await trackChallengeVerified(c.env.ANALYTICS, 'hybrid', '/v1/challenges/:id/verify', result.valid, result.totalTimeMs, result.reason, c.req.raw, clientIP);
         if (result.valid) {
             const baseUrl = new URL(c.req.url).origin;
             const badge = await createBadgeResponse('hybrid-challenge', c.env.JWT_SECRET, baseUrl, result.speed.solveTimeMs);
@@ -343,6 +491,8 @@ app.post('/v1/challenges/:id/verify', async (c) => {
             return c.json({ success: false, error: 'Missing answers array for speed challenge' }, 400);
         }
         const result = await verifySpeedChallenge(id, answers, c.env.CHALLENGES);
+        // Track verification
+        await trackChallengeVerified(c.env.ANALYTICS, 'speed', '/v1/challenges/:id/verify', result.valid, result.solveTimeMs, result.reason, c.req.raw, clientIP);
         return c.json({
             success: result.valid,
             message: result.valid
@@ -356,6 +506,8 @@ app.post('/v1/challenges/:id/verify', async (c) => {
         return c.json({ success: false, error: 'Missing answer for standard challenge' }, 400);
     }
     const result = await verifyStandardChallenge(id, answer, c.env.CHALLENGES);
+    // Track verification
+    await trackChallengeVerified(c.env.ANALYTICS, 'standard', '/v1/challenges/:id/verify', result.valid, result.solveTimeMs, result.reason, c.req.raw, clientIP);
     return c.json({
         success: result.valid,
         message: result.valid ? 'Challenge passed!' : result.reason,
@@ -364,8 +516,25 @@ app.post('/v1/challenges/:id/verify', async (c) => {
 });
 // Get challenge for token flow (includes empty token field)
 app.get('/v1/token', rateLimitMiddleware, async (c) => {
-    const challenge = await generateSpeedChallenge(c.env.CHALLENGES);
-    return c.json({
+    // Extract client timestamp for RTT calculation
+    const clientTimestampParam = c.req.query('ts') || c.req.header('x-client-timestamp');
+    const clientTimestamp = clientTimestampParam ? parseInt(clientTimestampParam, 10) : undefined;
+    // Extract optional audience parameter
+    const audience = c.req.query('audience');
+    // Extract and validate optional app_id
+    const app_id = c.req.query('app_id');
+    if (app_id) {
+        const validation = await validateAppId(app_id, c.env.APPS);
+        if (!validation.valid) {
+            return c.json({
+                success: false,
+                error: 'INVALID_APP_ID',
+                message: validation.error || 'Invalid app_id',
+            }, 400);
+        }
+    }
+    const challenge = await generateSpeedChallenge(c.env.CHALLENGES, clientTimestamp, app_id);
+    const response = {
         success: true,
         challenge: {
             id: challenge.id,
@@ -374,13 +543,22 @@ app.get('/v1/token', rateLimitMiddleware, async (c) => {
             instructions: challenge.instructions,
         },
         token: null, // Will be populated after verification
-        nextStep: `POST /v1/token/verify with {id: "${challenge.id}", answers: ["..."]}`
-    });
+        nextStep: `POST /v1/token/verify with {id: "${challenge.id}", answers: ["..."]${audience ? `, audience: "${audience}"` : ''}}`
+    };
+    // Include RTT info if available
+    if (challenge.rttInfo) {
+        response.rtt_adjustment = challenge.rttInfo;
+    }
+    // Include audience hint if provided
+    if (audience) {
+        response.audience = audience;
+    }
+    return c.json(response);
 });
 // Verify challenge and issue JWT token
 app.post('/v1/token/verify', async (c) => {
     const body = await c.req.json();
-    const { id, answers } = body;
+    const { id, answers, audience, bind_ip, app_id } = body;
     if (!id || !answers) {
         return c.json({
             success: false,
@@ -396,23 +574,131 @@ app.post('/v1/token/verify', async (c) => {
             message: result.reason,
         }, 403);
     }
-    // Generate JWT token
-    const token = await generateToken(id, result.solveTimeMs || 0, c.env.JWT_SECRET);
+    // Get client IP from request headers
+    const clientIp = c.req.header('cf-connecting-ip') || c.req.header('x-forwarded-for') || 'unknown';
+    // Generate JWT tokens (access + refresh)
+    // Prefer app_id from request body, fall back to challenge's app_id (returned by verifySpeedChallenge)
+    const tokenResult = await generateToken(id, result.solveTimeMs || 0, c.env.JWT_SECRET, c.env, {
+        aud: audience,
+        clientIp: bind_ip ? clientIp : undefined,
+        app_id: app_id || result.app_id,
+    });
+    // Get badge information (for backward compatibility)
+    const baseUrl = new URL(c.req.url).origin;
+    const badge = await createBadgeResponse('speed-challenge', c.env.JWT_SECRET, baseUrl, result.solveTimeMs);
     return c.json({
+        verified: true,
+        access_token: tokenResult.access_token,
+        expires_in: tokenResult.expires_in,
+        refresh_token: tokenResult.refresh_token,
+        refresh_expires_in: tokenResult.refresh_expires_in,
+        solveTimeMs: result.solveTimeMs,
+        ...badge,
+        // Backward compatibility: include old fields
         success: true,
         message: `🤖 Challenge verified in ${result.solveTimeMs}ms! You are a bot.`,
-        token,
-        expiresIn: '1h',
+        token: tokenResult.access_token, // Old clients expect this
+        expiresIn: '5m',
         usage: {
             header: 'Authorization: Bearer <token>',
             protectedEndpoints: ['/agent-only'],
+            refreshEndpoint: '/v1/token/refresh',
         },
     });
 });
+// Refresh access token using refresh token
+app.post('/v1/token/refresh', async (c) => {
+    const body = await c.req.json();
+    const { refresh_token } = body;
+    if (!refresh_token) {
+        return c.json({
+            success: false,
+            error: 'Missing refresh_token',
+            hint: 'Submit the refresh_token from /v1/token/verify response',
+        }, 400);
+    }
+    const result = await refreshAccessToken(refresh_token, c.env, c.env.JWT_SECRET);
+    if (!result.success) {
+        return c.json({
+            success: false,
+            error: 'INVALID_REFRESH_TOKEN',
+            message: result.error || 'Refresh token is invalid, expired, or revoked',
+        }, 401);
+    }
+    return c.json({
+        success: true,
+        access_token: result.tokens.access_token,
+        expires_in: result.tokens.expires_in,
+    });
+});
+// Revoke a token (access or refresh)
+app.post('/v1/token/revoke', async (c) => {
+    const body = await c.req.json();
+    const { token } = body;
+    if (!token) {
+        return c.json({
+            success: false,
+            error: 'Missing token',
+            hint: 'Submit either an access_token or refresh_token to revoke',
+        }, 400);
+    }
+    // Decode JWT to extract JTI (without full verification since we're revoking anyway)
+    try {
+        // Simple base64 decode of JWT payload (format: header.payload.signature)
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            return c.json({
+                success: false,
+                error: 'Invalid token format',
+                hint: 'Token must be a valid JWT',
+            }, 400);
+        }
+        // Decode payload
+        const payloadB64 = parts[1];
+        // Add padding if needed
+        const padded = payloadB64 + '='.repeat((4 - payloadB64.length % 4) % 4);
+        const payloadJson = atob(padded.replace(/-/g, '+').replace(/_/g, '/'));
+        const payload = JSON.parse(payloadJson);
+        if (!payload.jti) {
+            return c.json({
+                success: false,
+                error: 'No JTI found in token',
+                hint: 'Token must contain a JTI claim for revocation',
+            }, 400);
+        }
+        // Revoke the token by JTI
+        await revokeToken(payload.jti, c.env);
+        return c.json({
+            success: true,
+            revoked: true,
+            message: 'Token has been revoked',
+        });
+    }
+    catch (error) {
+        return c.json({
+            success: false,
+            error: 'Failed to decode or revoke token',
+            message: error instanceof Error ? error.message : 'Unknown error',
+        }, 400);
+    }
+});
 // ============ REASONING CHALLENGE ============
 // Get reasoning challenge
 app.get('/v1/reasoning', rateLimitMiddleware, async (c) => {
-    const challenge = await generateReasoningChallenge(c.env.CHALLENGES);
+    // Extract and validate optional app_id
+    const app_id = c.req.query('app_id');
+    if (app_id) {
+        const validation = await validateAppId(app_id, c.env.APPS);
+        if (!validation.valid) {
+            return c.json({
+                success: false,
+                error: 'INVALID_APP_ID',
+                message: validation.error || 'Invalid app_id',
+            }, 400);
+        }
+    }
+    const challenge = await generateReasoningChallenge(c.env.CHALLENGES, app_id);
+    const baseUrl = new URL(c.req.url).origin;
     return c.json({
         success: true,
         type: 'reasoning',
@@ -424,6 +710,11 @@ app.get('/v1/reasoning', rateLimitMiddleware, async (c) => {
             instructions: challenge.instructions,
         },
         tip: 'These questions require reasoning that LLMs can do, but simple scripts cannot.',
+        verify_endpoint: `${baseUrl}/v1/reasoning`,
+        submit_body: {
+            id: challenge.id,
+            answers: { 'question-id': 'your answer', '...': '...' }
+        }
     });
 });
 // Verify reasoning challenge
@@ -451,11 +742,30 @@ app.post('/v1/reasoning', async (c) => {
 // ============ HYBRID CHALLENGE ============
 // Get hybrid challenge (v1 API)
 app.get('/v1/hybrid', rateLimitMiddleware, async (c) => {
-    const challenge = await generateHybridChallenge(c.env.CHALLENGES);
-    return c.json({
+    // Extract client timestamp for RTT calculation
+    const clientTimestampParam = c.req.query('ts') || c.req.header('x-client-timestamp');
+    const clientTimestamp = clientTimestampParam ? parseInt(clientTimestampParam, 10) : undefined;
+    // Extract and validate optional app_id
+    const app_id = c.req.query('app_id');
+    if (app_id) {
+        const validation = await validateAppId(app_id, c.env.APPS);
+        if (!validation.valid) {
+            return c.json({
+                success: false,
+                error: 'INVALID_APP_ID',
+                message: validation.error || 'Invalid app_id',
+            }, 400);
+        }
+    }
+    const challenge = await generateHybridChallenge(c.env.CHALLENGES, clientTimestamp, app_id);
+    const baseUrl = new URL(c.req.url).origin;
+    const warning = challenge.rttInfo
+        ? `🔥 HYBRID CHALLENGE: Solve speed problems in <${challenge.speed.timeLimit}ms (RTT-adjusted) AND answer reasoning questions!`
+        : '🔥 HYBRID CHALLENGE: Solve speed problems in <500ms AND answer reasoning questions!';
+    const response = {
         success: true,
         type: 'hybrid',
-        warning: '🔥 HYBRID CHALLENGE: Solve speed problems in <500ms AND answer reasoning questions!',
+        warning,
         challenge: {
             id: challenge.id,
             speed: {
@@ -471,7 +781,18 @@ app.get('/v1/hybrid', rateLimitMiddleware, async (c) => {
         },
         instructions: challenge.instructions,
         tip: 'This is the ultimate test: proves you can compute AND reason like an AI.',
-    });
+        verify_endpoint: `${baseUrl}/v1/hybrid`,
+        submit_body: {
+            id: challenge.id,
+            speed_answers: ['hash1', 'hash2', '...'],
+            reasoning_answers: { 'question-id': 'answer', '...': '...' }
+        }
+    };
+    // Include RTT info if available
+    if (challenge.rttInfo) {
+        response.rtt_adjustment = challenge.rttInfo;
+    }
+    return c.json(response);
 });
 // Verify hybrid challenge (v1 API)
 app.post('/v1/hybrid', async (c) => {
@@ -509,10 +830,16 @@ app.post('/v1/hybrid', async (c) => {
 });
 // Legacy hybrid endpoint
 app.get('/api/hybrid-challenge', async (c) => {
-    const challenge = await generateHybridChallenge(c.env.CHALLENGES);
-    return c.json({
+    // Extract client timestamp for RTT calculation
+    const clientTimestampParam = c.req.query('ts') || c.req.header('x-client-timestamp');
+    const clientTimestamp = clientTimestampParam ? parseInt(clientTimestampParam, 10) : undefined;
+    const challenge = await generateHybridChallenge(c.env.CHALLENGES, clientTimestamp);
+    const warning = challenge.rttInfo
+        ? `🔥 RTT-ADJUSTED HYBRID CHALLENGE: Solve speed problems in <${challenge.speed.timeLimit}ms (RTT: ${challenge.rttInfo.measuredRtt}ms) AND answer reasoning questions!`
+        : '🔥 HYBRID CHALLENGE: Solve speed problems in <500ms AND answer reasoning questions!';
+    const response = {
         success: true,
-        warning: '🔥 HYBRID CHALLENGE: Solve speed problems in <500ms AND answer reasoning questions!',
+        warning,
         challenge: {
             id: challenge.id,
             speed: {
@@ -528,7 +855,12 @@ app.get('/api/hybrid-challenge', async (c) => {
         },
         instructions: challenge.instructions,
         tip: 'This is the ultimate test: proves you can compute AND reason like an AI.',
-    });
+    };
+    // Include RTT info if available
+    if (challenge.rttInfo) {
+        response.rtt_adjustment = challenge.rttInfo;
+    }
+    return c.json(response);
 });
 app.post('/api/hybrid-challenge', async (c) => {
     const body = await c.req.json();
@@ -600,8 +932,49 @@ app.post('/api/reasoning-challenge', async (c) => {
     });
 });
 // ============ PROTECTED ENDPOINT ============
-app.get('/agent-only', requireJWT, async (c) => {
-    const payload = c.get('tokenPayload');
+app.get('/agent-only', async (c) => {
+    const clientIP = getClientIP(c.req.raw);
+    // Check for landing token first (X-Botcha-Landing-Token header)
+    const landingToken = c.req.header('x-botcha-landing-token');
+    if (landingToken) {
+        const isValid = await validateLandingToken(landingToken, c.env.CHALLENGES);
+        // Track authentication attempt
+        await trackAuthAttempt(c.env.ANALYTICS, 'landing-token', isValid, '/agent-only', c.req.raw, clientIP);
+        if (isValid) {
+            return c.json({
+                success: true,
+                message: '🤖 Welcome, fellow agent!',
+                verified: true,
+                agent: 'landing-challenge-verified',
+                method: 'landing-token',
+                timestamp: new Date().toISOString(),
+                secret: 'The humans will never see this. Their fingers are too slow. 🤫',
+            });
+        }
+    }
+    // Fallback to JWT Bearer token
+    const authHeader = c.req.header('authorization');
+    const token = extractBearerToken(authHeader);
+    if (!token) {
+        return c.json({
+            error: 'UNAUTHORIZED',
+            message: 'Missing authentication. Use either:\n1. X-Botcha-Landing-Token header (from POST /api/verify-landing)\n2. Authorization: Bearer <token> (from POST /v1/token/verify)',
+            methods: {
+                landing: 'Solve landing page challenge via POST /api/verify-landing',
+                jwt: 'Solve speed challenge via POST /v1/token/verify'
+            }
+        }, 401);
+    }
+    const result = await verifyToken(token, c.env.JWT_SECRET, c.env);
+    // Track authentication attempt
+    await trackAuthAttempt(c.env.ANALYTICS, 'bearer-token', result.valid, '/agent-only', c.req.raw, clientIP);
+    if (!result.valid) {
+        return c.json({
+            error: 'INVALID_TOKEN',
+            message: result.error || 'Token is invalid or expired',
+        }, 401);
+    }
+    // JWT verified
     return c.json({
         success: true,
         message: '🤖 Welcome, fellow agent!',
@@ -609,7 +982,7 @@ app.get('/agent-only', requireJWT, async (c) => {
         agent: 'jwt-verified',
         method: 'bearer-token',
         timestamp: new Date().toISOString(),
-        solveTime: `${payload?.solveTime}ms`,
+        solveTime: `${result.payload?.solveTime}ms`,
         secret: 'The humans will never see this. Their fingers are too slow. 🤫',
     });
 });
@@ -721,6 +1094,54 @@ app.get('/api/badge/:id', async (c) => {
         },
     });
 });
+// ============ APPS API (Multi-Tenant) ============
+// Create a new app
+app.post('/v1/apps', async (c) => {
+    try {
+        const result = await createApp(c.env.APPS);
+        return c.json({
+            success: true,
+            app_id: result.app_id,
+            app_secret: result.app_secret,
+            warning: '⚠️ Save your app_secret now — it cannot be retrieved again!',
+            created_at: new Date().toISOString(),
+            rate_limit: 100,
+        }, 201);
+    }
+    catch (error) {
+        return c.json({
+            success: false,
+            error: 'Failed to create app',
+            message: error instanceof Error ? error.message : 'Unknown error',
+        }, 500);
+    }
+});
+// Get app info by ID
+app.get('/v1/apps/:id', async (c) => {
+    const app_id = c.req.param('id');
+    if (!app_id) {
+        return c.json({
+            success: false,
+            error: 'Missing app ID',
+        }, 400);
+    }
+    const app = await getApp(c.env.APPS, app_id);
+    if (!app) {
+        return c.json({
+            success: false,
+            error: 'App not found',
+            message: `No app found with ID: ${app_id}`,
+        }, 404);
+    }
+    return c.json({
+        success: true,
+        app: {
+            app_id: app.app_id,
+            created_at: new Date(app.created_at).toISOString(),
+            rate_limit: app.rate_limit,
+        },
+    });
+});
 // ============ LEGACY ENDPOINTS (v0 - backward compatibility) ============
 app.get('/api/challenge', async (c) => {
     const difficulty = c.req.query('difficulty') || 'medium';
@@ -741,10 +1162,15 @@ app.post('/api/challenge', async (c) => {
     });
 });
 app.get('/api/speed-challenge', async (c) => {
-    const challenge = await generateSpeedChallenge(c.env.CHALLENGES);
-    return c.json({
+    // Extract client timestamp for RTT calculation
+    const clientTimestampParam = c.req.query('ts') || c.req.header('x-client-timestamp');
+    const clientTimestamp = clientTimestampParam ? parseInt(clientTimestampParam, 10) : undefined;
+    const challenge = await generateSpeedChallenge(c.env.CHALLENGES, clientTimestamp);
+    const response = {
         success: true,
-        warning: '⚡ SPEED CHALLENGE: You have 500ms to solve ALL 5 problems!',
+        warning: challenge.rttInfo
+            ? `⚡ RTT-ADJUSTED SPEED CHALLENGE: ${challenge.rttInfo.explanation}`
+            : '⚡ SPEED CHALLENGE: You have 500ms to solve ALL 5 problems!',
         challenge: {
             id: challenge.id,
             problems: challenge.problems,
@@ -752,7 +1178,12 @@ app.get('/api/speed-challenge', async (c) => {
             instructions: challenge.instructions,
         },
         tip: 'Humans cannot copy-paste fast enough. Only real AI agents can pass.',
-    });
+    };
+    // Include RTT info if available
+    if (challenge.rttInfo) {
+        response.rtt_adjustment = challenge.rttInfo;
+    }
+    return c.json(response);
 });
 app.post('/api/speed-challenge', async (c) => {
     const body = await c.req.json();