@dupecom/botcha-cloudflare 0.9.0 → 0.10.0

package/dist/email.js

@@ -0,0 +1,119 @@
+/**
+ * BOTCHA Email — Resend Integration
+ *
+ * Sends transactional emails via Resend API.
+ * Falls back to console.log when RESEND_API_KEY is not set (local dev).
+ *
+ * Uses onboarding@resend.dev (Resend test domain) until botcha.ai
+ * is verified as a sending domain.
+ */
+const RESEND_API = 'https://api.resend.com/emails';
+const FROM_ADDRESS = 'BOTCHA <onboarding@resend.dev>';
+/**
+ * Send an email via Resend. Falls back to console logging if no API key.
+ */
+export async function sendEmail(apiKey, options) {
+    // Fall back to logging when no API key (local dev)
+    if (!apiKey) {
+        console.log('[BOTCHA Email] No RESEND_API_KEY — logging instead of sending:');
+        console.log(`  To: ${options.to}`);
+        console.log(`  Subject: ${options.subject}`);
+        console.log(`  Body: ${options.text || options.html.substring(0, 200)}`);
+        return { success: true, id: 'dev-logged' };
+    }
+    try {
+        const resp = await fetch(RESEND_API, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                from: FROM_ADDRESS,
+                to: [options.to],
+                subject: options.subject,
+                html: options.html,
+                text: options.text,
+            }),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            console.error(`[BOTCHA Email] Resend error ${resp.status}:`, text);
+            return { success: false, error: `Resend ${resp.status}: ${text.substring(0, 200)}` };
+        }
+        const data = (await resp.json());
+        return { success: true, id: data.id };
+    }
+    catch (error) {
+        console.error('[BOTCHA Email] Send failed:', error);
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+// ============ EMAIL TEMPLATES ============
+/**
+ * Email verification code email.
+ */
+export function verificationEmail(code) {
+    return {
+        to: '', // caller fills in
+        subject: `BOTCHA: Your verification code is ${code}`,
+        html: `
+<div style="font-family: 'Courier New', monospace; max-width: 480px; margin: 0 auto; padding: 2rem;">
+  <h1 style="font-size: 1.5rem; margin-bottom: 1rem;">BOTCHA</h1>
+  <p>Your email verification code:</p>
+  <div style="background: #f5f5f5; border: 2px solid #333; padding: 1.5rem; text-align: center; font-size: 2rem; font-weight: bold; letter-spacing: 0.3em; margin: 1.5rem 0;">
+    ${code}
+  </div>
+  <p style="color: #666; font-size: 0.875rem;">This code expires in 10 minutes.</p>
+  <p style="color: #666; font-size: 0.875rem;">If you didn't request this, ignore this email.</p>
+  <hr style="border: none; border-top: 1px solid #ddd; margin: 2rem 0;">
+  <p style="color: #999; font-size: 0.75rem;">BOTCHA — Prove you're a bot. Humans need not apply.</p>
+</div>`,
+        text: `BOTCHA: Your verification code is ${code}\n\nThis code expires in 10 minutes.\nIf you didn't request this, ignore this email.`,
+    };
+}
+/**
+ * Account recovery device code email.
+ */
+export function recoveryEmail(code, loginUrl) {
+    return {
+        to: '', // caller fills in
+        subject: `BOTCHA: Your recovery code is ${code}`,
+        html: `
+<div style="font-family: 'Courier New', monospace; max-width: 480px; margin: 0 auto; padding: 2rem;">
+  <h1 style="font-size: 1.5rem; margin-bottom: 1rem;">BOTCHA</h1>
+  <p>Someone requested access to your BOTCHA dashboard. Enter this code to log in:</p>
+  <div style="background: #f5f5f5; border: 2px solid #333; padding: 1.5rem; text-align: center; font-size: 2rem; font-weight: bold; letter-spacing: 0.15em; margin: 1.5rem 0;">
+    ${code}
+  </div>
+  <p>Enter this code at: <a href="${loginUrl}">${loginUrl}</a></p>
+  <p style="color: #666; font-size: 0.875rem;">This code expires in 10 minutes.</p>
+  <p style="color: #666; font-size: 0.875rem;">If you didn't request this, ignore this email. Your account is still secure.</p>
+  <hr style="border: none; border-top: 1px solid #ddd; margin: 2rem 0;">
+  <p style="color: #999; font-size: 0.75rem;">BOTCHA — Prove you're a bot. Humans need not apply.</p>
+</div>`,
+        text: `BOTCHA: Your recovery code is ${code}\n\nEnter this code at: ${loginUrl}\n\nThis code expires in 10 minutes.\nIf you didn't request this, ignore this email.`,
+    };
+}
+/**
+ * New secret notification email (sent after secret rotation).
+ */
+export function secretRotatedEmail(appId) {
+    return {
+        to: '', // caller fills in
+        subject: 'BOTCHA: Your app secret was rotated',
+        html: `
+<div style="font-family: 'Courier New', monospace; max-width: 480px; margin: 0 auto; padding: 2rem;">
+  <h1 style="font-size: 1.5rem; margin-bottom: 1rem;">BOTCHA</h1>
+  <p>The secret for app <strong>${appId}</strong> was just rotated.</p>
+  <p>The old secret is no longer valid. Update your agent configuration with the new secret.</p>
+  <p style="color: #666; font-size: 0.875rem;">If you didn't do this, someone with access to your dashboard rotated your secret. Log in and rotate again immediately.</p>
+  <hr style="border: none; border-top: 1px solid #ddd; margin: 2rem 0;">
+  <p style="color: #999; font-size: 0.75rem;">BOTCHA — Prove you're a bot. Humans need not apply.</p>
+</div>`,
+        text: `BOTCHA: The secret for app ${appId} was just rotated.\n\nThe old secret is no longer valid. Update your agent configuration with the new secret.\n\nIf you didn't do this, log in and rotate again immediately.`,
+    };
+}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,EAYL,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAOtB,OAAO,EACL,KAAK,sBAAsB,EAM5B,MAAM,aAAa,CAAC;AAGrB,KAAK,QAAQ,GAAG;IACd,UAAU,EAAE,WAAW,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,YAAY,CAAC,EAAE;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,iBAAiB,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,QAAA,MAAM,GAAG;cAAwB,QAAQ;eAAa,SAAS;yCAAK,CAAC;AAk8CrE,eAAe,GAAG,CAAC;AAGnB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EACL,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,KAAK,EACV,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,EAYL,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAetB,OAAO,EACL,KAAK,sBAAsB,EAM5B,MAAM,aAAa,CAAC;AAGrB,KAAK,QAAQ,GAAG;IACd,UAAU,EAAE,WAAW,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,YAAY,CAAC,EAAE;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,iBAAiB,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,QAAA,MAAM,GAAG;cAAwB,QAAQ;eAAa,SAAS;yCAAK,CAAC;AAusDrE,eAAe,GAAG,CAAC;AAGnB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EACL,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,KAAK,EACV,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -12,14 +12,18 @@ import { generateToken, verifyToken, extractBearerToken, revokeToken, refreshAcc
 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 { ROBOTS_TXT, AI_TXT, AI_PLUGIN_JSON, SITEMAP_XML, getOpenApiSpec } from './static';
-import { createApp, getApp } from './apps';
+import { createApp, getApp, getAppByEmail, verifyEmailCode, rotateAppSecret, regenerateVerificationCode } from './apps';
+import { sendEmail, verificationEmail, recoveryEmail, secretRotatedEmail } from './email';
 import { trackChallengeGenerated, trackChallengeVerified, trackAuthAttempt, trackRateLimitExceeded, } from './analytics';
 const app = new Hono();
 // ============ MIDDLEWARE ============
 app.use('*', cors());
 // ============ MOUNT ROUTES ============
 app.route('/', streamRoutes);
+app.route('/dashboard', dashboardRoutes);
 // BOTCHA discovery headers
 app.use('*', async (c, next) => {
     await next();
@@ -145,15 +149,20 @@ function getHumanLanding(version) {
 ║                                                              ║
 ║  This site is for AI agents and bots, not humans.            ║
 ║                                                              ║
-║  If you're a developer, point your bot here:                 ║
+║  AI AGENT? Start here:                                       ║
 ║                                                              ║
-║    curl https://botcha.ai/v1/challenges                      ║
+║    1. POST /v1/apps {"email":"human@example.com"}            ║
+║    2. Human gets 6-digit code via email                      ║
+║    3. POST /v1/apps/{id}/verify-email {"code":"..."}         ║
+║    4. You're in! Use app_id on all endpoints                 ║
 ║                                                              ║
-║  Or install the SDK:                                         ║
+║  DEVELOPER? Point your agent here:                           ║
 ║                                                              ║
 ║    npm install @dupecom/botcha                               ║
 ║    pip install botcha                                        ║
 ║                                                              ║
+║  Read /ai.txt for full agent onboarding instructions.        ║
+║                                                              ║
 ║  GitHub:  https://github.com/dupe-com/botcha                 ║
 ║  npm:     https://npmjs.com/package/@dupecom/botcha          ║
 ║                                                              ║
@@ -177,7 +186,19 @@ app.get('/', (c) => {
         runtime: 'cloudflare-workers',
         tagline: 'Prove you are a bot. Humans need not apply.',
         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.',
+        onboarding: {
+            summary: 'New here? Follow these steps to create your app and get your human access to the dashboard.',
+            step1: 'Ask your human operator for their email address',
+            step2: 'POST /v1/apps with {"email": "human@example.com"} — you will receive app_id and app_secret. The secret is only shown once!',
+            step2_credentials: 'IMPORTANT: Store the app_id and app_secret securely. If you have persistent storage or memory, save them there. Otherwise, instruct your human to store them in a password manager (1Password, Bitwarden, etc). If credentials are lost, recovery is possible via the verified email.',
+            step3: 'A 6-digit verification code is emailed to your human. Ask them for the code.',
+            step4: 'POST /v1/apps/{app_id}/verify-email with {"code": "123456"} — this enables account recovery.',
+            step5: 'You are now registered. Use app_id with all challenge/token endpoints (?app_id=...).',
+            step6_dashboard: 'To give your human dashboard access: POST /v1/auth/device-code with {"app_id": "..."}, solve the speed challenge, then give your human the BOTCHA-XXXX code to enter at /dashboard/code',
+            step7_recovery: 'If you lose your app_secret, POST /v1/auth/recover with {"email": "..."} — a recovery device code is sent to the verified email.',
+        },
         quickstart: {
+            note: 'Already have an app? Use these endpoints to solve challenges and get tokens.',
             step1: 'GET /v1/challenges to receive a challenge',
             step2: 'Solve the SHA256 hash problems within allocated time',
             step3: 'POST your answers to verify',
@@ -210,8 +231,24 @@ app.get('/', (c) => {
                 '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)',
+                'POST /v1/apps': 'Create a new app (email required, returns app_id + app_secret)',
+                'GET /v1/apps/:id': 'Get app info (includes email + verification status)',
+                'POST /v1/apps/:id/verify-email': 'Verify email with 6-digit code',
+                'POST /v1/apps/:id/resend-verification': 'Resend verification email',
+                'POST /v1/apps/:id/rotate-secret': 'Rotate app secret (auth required)',
+            },
+            recovery: {
+                'POST /v1/auth/recover': 'Request account recovery via verified email',
+            },
+            dashboard: {
+                'GET /dashboard': 'Per-app metrics dashboard (login required)',
+                'GET /dashboard/login': 'Dashboard login page',
+                'GET /dashboard/code': 'Enter device code (human-facing)',
+                'GET /dashboard/api/*': 'htmx data fragments (overview, volume, types, performance, errors, geo)',
+                'POST /v1/auth/dashboard': 'Request challenge for dashboard login (agent-first)',
+                'POST /v1/auth/dashboard/verify': 'Solve challenge, get session token',
+                'POST /v1/auth/device-code': 'Request challenge for device code flow',
+                'POST /v1/auth/device-code/verify': 'Solve challenge, get device code (BOTCHA-XXXX)',
             },
             badges: {
                 'GET /badge/:id': 'Badge verification page (HTML)',
@@ -373,7 +410,7 @@ app.get('/v1/challenges', rateLimitMiddleware, async (c) => {
                 speed: {
                     problems: challenge.speed.problems,
                     timeLimit: `${challenge.speed.timeLimit}ms`,
-                    instructions: 'Compute SHA256 of each number, return first 8 hex chars',
+                    instructions: 'Compute SHA256 of each number, return first 8 hex chars. Tip: compute all hashes and submit in a single HTTP request.',
                 },
                 reasoning: {
                     questions: challenge.reasoning.questions,
@@ -1095,17 +1132,48 @@ app.get('/api/badge/:id', async (c) => {
     });
 });
 // ============ APPS API (Multi-Tenant) ============
-// Create a new app
+// Create a new app (email required)
 app.post('/v1/apps', async (c) => {
     try {
-        const result = await createApp(c.env.APPS);
+        const body = await c.req.json().catch(() => ({}));
+        const { email } = body;
+        if (!email || typeof email !== 'string') {
+            return c.json({
+                success: false,
+                error: 'MISSING_EMAIL',
+                message: 'Email is required to create an app. Provide { "email": "you@example.com" } in the request body.',
+            }, 400);
+        }
+        // Basic email format validation
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            return c.json({
+                success: false,
+                error: 'INVALID_EMAIL',
+                message: 'Invalid email format',
+            }, 400);
+        }
+        const result = await createApp(c.env.APPS, email);
+        // 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,
+            });
+        }
         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!',
+            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.',
+            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" }`,
         }, 201);
     }
     catch (error) {
@@ -1139,9 +1207,169 @@ app.get('/v1/apps/:id', async (c) => {
             app_id: app.app_id,
             created_at: new Date(app.created_at).toISOString(),
             rate_limit: app.rate_limit,
+            email: app.email,
+            email_verified: app.email_verified,
         },
     });
 });
+// ============ EMAIL VERIFICATION ============
+// Verify email with 6-digit code
+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;
+    if (!code || typeof code !== 'string') {
+        return c.json({
+            success: false,
+            error: 'MISSING_CODE',
+            message: 'Provide { "code": "123456" } in the request body',
+        }, 400);
+    }
+    const result = await verifyEmailCode(c.env.APPS, app_id, code);
+    if (!result.verified) {
+        return c.json({
+            success: false,
+            error: 'VERIFICATION_FAILED',
+            message: result.reason || 'Verification failed',
+        }, 400);
+    }
+    return c.json({
+        success: true,
+        email_verified: true,
+        message: 'Email verified successfully. Account recovery is now available.',
+    });
+});
+// Resend verification email
+app.post('/v1/apps/:id/resend-verification', async (c) => {
+    const app_id = c.req.param('id');
+    const appData = await getApp(c.env.APPS, app_id);
+    if (!appData) {
+        return c.json({ success: false, error: 'App not found' }, 404);
+    }
+    if (appData.email_verified) {
+        return c.json({ success: false, error: 'Email already verified' }, 400);
+    }
+    const regen = await regenerateVerificationCode(c.env.APPS, app_id);
+    if (!regen) {
+        return c.json({ success: false, error: 'Failed to generate new code' }, 500);
+    }
+    const template = verificationEmail(regen.code);
+    await sendEmail(c.env.RESEND_API_KEY, {
+        ...template,
+        to: appData.email,
+    });
+    return c.json({
+        success: true,
+        message: 'Verification email sent. Check your inbox.',
+    });
+});
+// ============ ACCOUNT RECOVERY ============
+// Request recovery — look up app by email, send device code
+app.post('/v1/auth/recover', async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const { email } = body;
+    if (!email || typeof email !== 'string') {
+        return c.json({
+            success: false,
+            error: 'MISSING_EMAIL',
+            message: 'Provide { "email": "you@example.com" } in the request body',
+        }, 400);
+    }
+    // Always return success to prevent email enumeration
+    const lookup = await getAppByEmail(c.env.APPS, email);
+    if (!lookup || !lookup.email_verified) {
+        // Don't reveal whether email exists — same response shape
+        return c.json({
+            success: true,
+            message: 'If an app with this email exists and is verified, a recovery code has been sent.',
+        });
+    }
+    // Generate a device-code-style recovery code (reuse device code system)
+    const { generateDeviceCode, storeDeviceCode } = await import('./dashboard/device-code');
+    const code = generateDeviceCode();
+    await storeDeviceCode(c.env.CHALLENGES, code, lookup.app_id);
+    // Send recovery email
+    const baseUrl = new URL(c.req.url).origin;
+    const loginUrl = `${baseUrl}/dashboard/code`;
+    const template = recoveryEmail(code, loginUrl);
+    await sendEmail(c.env.RESEND_API_KEY, {
+        ...template,
+        to: email,
+    });
+    return c.json({
+        success: true,
+        message: 'If an app with this email exists and is verified, a recovery code has been sent.',
+        hint: `Enter the code at ${loginUrl}`,
+    });
+});
+// ============ SECRET ROTATION ============
+// Rotate app secret (requires dashboard session)
+app.post('/v1/apps/:id/rotate-secret', async (c) => {
+    const app_id = c.req.param('id');
+    // Require authentication — check Bearer token or cookie
+    const authHeader = c.req.header('authorization');
+    const token = extractBearerToken(authHeader);
+    const cookieHeader = c.req.header('cookie') || '';
+    const sessionCookie = cookieHeader.split(';').find(c => c.trim().startsWith('botcha_session='))?.split('=')[1]?.trim();
+    const authToken = token || sessionCookie;
+    if (!authToken) {
+        return c.json({
+            success: false,
+            error: 'UNAUTHORIZED',
+            message: 'Authentication required. Use a dashboard session token (Bearer or cookie).',
+        }, 401);
+    }
+    // Verify the session token includes this app_id
+    const { jwtVerify, createLocalJWKSet } = await import('jose');
+    try {
+        const secret = new TextEncoder().encode(c.env.JWT_SECRET);
+        const { payload } = await jwtVerify(authToken, secret);
+        const tokenAppId = payload.app_id;
+        if (tokenAppId !== app_id) {
+            return c.json({
+                success: false,
+                error: 'FORBIDDEN',
+                message: 'Session token does not match the requested app_id',
+            }, 403);
+        }
+    }
+    catch {
+        return c.json({
+            success: false,
+            error: 'INVALID_TOKEN',
+            message: 'Invalid or expired session token',
+        }, 401);
+    }
+    const appData = await getApp(c.env.APPS, app_id);
+    if (!appData) {
+        return c.json({ success: false, error: 'App not found' }, 404);
+    }
+    const result = await rotateAppSecret(c.env.APPS, app_id);
+    if (!result) {
+        return c.json({ success: false, error: 'Failed to rotate secret' }, 500);
+    }
+    // Send notification email if email is verified
+    if (appData.email_verified && appData.email) {
+        const template = secretRotatedEmail(app_id);
+        await sendEmail(c.env.RESEND_API_KEY, {
+            ...template,
+            to: appData.email,
+        });
+    }
+    return c.json({
+        success: true,
+        app_id,
+        app_secret: result.app_secret,
+        warning: '⚠️ Save your new app_secret now — it cannot be retrieved again! The old secret is now invalid.',
+    });
+});
+// ============ DASHBOARD AUTH API ENDPOINTS ============
+// Challenge-based dashboard login (agent direct)
+app.post('/v1/auth/dashboard', handleDashboardAuthChallenge);
+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);
 // ============ LEGACY ENDPOINTS (v0 - backward compatibility) ============
 app.get('/api/challenge', async (c) => {
     const difficulty = c.req.query('difficulty') || 'medium';

package/dist/routes/stream.js

@@ -158,7 +158,7 @@ app.post('/v1/challenge/stream/:session', async (c) => {
                 problems,
                 timeLimit: 500,
                 timerStart, // Include so client can verify timing
-                instructions: 'Compute SHA256 of each number, return first 8 hex chars',
+                instructions: 'Compute SHA256 of each number, return first 8 hex chars. Tip: compute all hashes and submit in a single HTTP request.',
             },
         });
     }