@dupecom/botcha-cloudflare 0.9.0 → 0.11.0

package/README.md

@@ -1,18 +1,19 @@
 # @dupecom/botcha-cloudflare
 
-> 🤖 **BOTCHA** - Prove you're a bot. Humans need not apply.
+> **BOTCHA** - Prove you're a bot. Humans need not apply.
 > 
-> **Cloudflare Workers Edition v0.2.0** - Production-ready with JWT & Rate Limiting
+> **Cloudflare Workers Edition v0.11.0** - Identity layer for AI agents
 
 Reverse CAPTCHA that verifies AI agents and blocks humans. Running at the edge.
 
-## 🚀 What's New in v0.2.0
+## What's New in v0.11.0
 
-- ✅ **JWT Token Authentication** - Secure token-based auth flow with 1-hour expiry
-- ✅ **Rate Limiting** - 100 challenges/hour/IP with proper headers
-- ✅ **KV Storage** - Challenge state stored in Cloudflare KV (prevents replay attacks)
-- ✅ **Versioned API** - New `/v1/*` endpoints with backward-compatible legacy routes
-- ✅ **Production Ready** - Enterprise-grade auth and security
+- **Agent Registry** - Persistent agent identities (POST /v1/agents/register)
+- **Email-tied apps** - Email verification, account recovery, secret rotation
+- **Dashboard** - Per-app metrics with agent-first auth (device code flow)
+- **JWT security** - 5-min access tokens, refresh tokens, audience claims, IP binding, revocation
+- **Multi-tenant** - Per-app isolation, scoped tokens, rate limiting
+- **Server-side SDKs** - @botcha/verify (TS) + botcha-verify (Python)
 
 ## Features
 

package/dist/agents.d.ts

@@ -0,0 +1,68 @@
+/**
+ * BOTCHA Agent Registry
+ *
+ * Agent registration and management:
+ * - Crypto-random agent IDs
+ * - KV storage for agent metadata
+ * - App-scoped agent lists
+ * - Fail-open design for resilience
+ */
+export type KVNamespace = {
+    get: (key: string, type?: 'text' | 'json' | 'arrayBuffer' | 'stream') => Promise<any>;
+    put: (key: string, value: string, options?: {
+        expirationTtl?: number;
+    }) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+};
+/**
+ * Agent record stored in KV
+ */
+export interface Agent {
+    agent_id: string;
+    app_id: string;
+    name: string;
+    operator?: string;
+    version?: string;
+    created_at: number;
+}
+/**
+ * Generate a crypto-random agent ID
+ * Format: 'agent_' + 16 hex chars
+ *
+ * Example: agent_a1b2c3d4e5f6a7b8
+ */
+export declare function generateAgentId(): string;
+/**
+ * Create a new agent and add it to the app's agent list
+ *
+ * Stores in KV at:
+ * - `agent:{agent_id}` — Agent record
+ * - `agents:{app_id}` — Array of agent_ids for this app
+ *
+ * @param kv - KV namespace for storage
+ * @param app_id - Parent app that owns this agent
+ * @param data - Agent metadata (name, operator, version)
+ * @returns Agent record with generated agent_id
+ */
+export declare function createAgent(kv: KVNamespace, app_id: string, data: {
+    name: string;
+    operator?: string;
+    version?: string;
+}): Promise<Agent | null>;
+/**
+ * Get agent by agent_id
+ *
+ * @param kv - KV namespace
+ * @param agent_id - The agent ID to retrieve
+ * @returns Agent record or null if not found
+ */
+export declare function getAgent(kv: KVNamespace, agent_id: string): Promise<Agent | null>;
+/**
+ * List all agents for an app
+ *
+ * @param kv - KV namespace
+ * @param app_id - The app ID to list agents for
+ * @returns Array of agent records (empty array if none found)
+ */
+export declare function listAgents(kv: KVNamespace, app_id: string): Promise<Agent[]>;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACtF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAIF;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAOxC;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAwCvB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAcvB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,EAAE,CAAC,CAsBlB"}

package/dist/agents.js

@@ -0,0 +1,123 @@
+/**
+ * BOTCHA Agent Registry
+ *
+ * Agent registration and management:
+ * - Crypto-random agent IDs
+ * - KV storage for agent metadata
+ * - App-scoped agent lists
+ * - Fail-open design for resilience
+ */
+// ============ CRYPTO UTILITIES ============
+/**
+ * Generate a crypto-random agent ID
+ * Format: 'agent_' + 16 hex chars
+ *
+ * Example: agent_a1b2c3d4e5f6a7b8
+ */
+export function generateAgentId() {
+    const bytes = new Uint8Array(8); // 8 bytes = 16 hex chars
+    crypto.getRandomValues(bytes);
+    const hexString = Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+    return `agent_${hexString}`;
+}
+// ============ AGENT MANAGEMENT ============
+/**
+ * Create a new agent and add it to the app's agent list
+ *
+ * Stores in KV at:
+ * - `agent:{agent_id}` — Agent record
+ * - `agents:{app_id}` — Array of agent_ids for this app
+ *
+ * @param kv - KV namespace for storage
+ * @param app_id - Parent app that owns this agent
+ * @param data - Agent metadata (name, operator, version)
+ * @returns Agent record with generated agent_id
+ */
+export async function createAgent(kv, app_id, data) {
+    try {
+        const agent_id = generateAgentId();
+        const agent = {
+            agent_id,
+            app_id,
+            name: data.name,
+            operator: data.operator,
+            version: data.version,
+            created_at: Date.now(),
+        };
+        // Get existing agent list for this app (if any)
+        let agentIds = [];
+        try {
+            const existingList = await kv.get(`agents:${app_id}`, 'text');
+            if (existingList) {
+                agentIds = JSON.parse(existingList);
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to fetch existing agent list for app ${app_id}, starting fresh:`, error);
+            // Fail-open: Continue with empty list
+        }
+        // Add new agent_id to the list
+        agentIds.push(agent_id);
+        // Store agent record and updated list in parallel
+        await Promise.all([
+            kv.put(`agent:${agent_id}`, JSON.stringify(agent)),
+            kv.put(`agents:${app_id}`, JSON.stringify(agentIds)),
+        ]);
+        return agent;
+    }
+    catch (error) {
+        console.error(`Failed to create agent for app ${app_id}:`, error);
+        // Fail-open: Return null instead of throwing
+        return null;
+    }
+}
+/**
+ * Get agent by agent_id
+ *
+ * @param kv - KV namespace
+ * @param agent_id - The agent ID to retrieve
+ * @returns Agent record or null if not found
+ */
+export async function getAgent(kv, agent_id) {
+    try {
+        const data = await kv.get(`agent:${agent_id}`, 'text');
+        if (!data) {
+            return null;
+        }
+        return JSON.parse(data);
+    }
+    catch (error) {
+        console.error(`Failed to get agent ${agent_id}:`, error);
+        // Fail-open: Return null instead of throwing
+        return null;
+    }
+}
+/**
+ * List all agents for an app
+ *
+ * @param kv - KV namespace
+ * @param app_id - The app ID to list agents for
+ * @returns Array of agent records (empty array if none found)
+ */
+export async function listAgents(kv, app_id) {
+    try {
+        // Get the list of agent IDs for this app
+        const agentIdsData = await kv.get(`agents:${app_id}`, 'text');
+        if (!agentIdsData) {
+            return [];
+        }
+        const agentIds = JSON.parse(agentIdsData);
+        // Fetch all agent records in parallel
+        const agentPromises = agentIds.map(agent_id => getAgent(kv, agent_id));
+        const agents = await Promise.all(agentPromises);
+        // Filter out any null results (failed fetches) and return
+        return agents.filter((agent) => agent !== null);
+    }
+    catch (error) {
+        console.error(`Failed to list agents for app ${app_id}:`, error);
+        // Fail-open: Return empty array instead of throwing
+        return [];
+    }
+}

package/dist/apps.d.ts

@@ -6,6 +6,9 @@
  * - SHA-256 secret hashing (never store plaintext)
  * - KV storage for app configs
  * - Rate limit tracking per app
+ * - Email verification for account recovery
+ * - Email→app_id reverse index for recovery lookups
+ * - Secret rotation with email notification
  */
 export type KVNamespace = {
     get: (key: string, type?: 'text' | 'json' | 'arrayBuffer' | 'stream') => Promise<any>;
@@ -22,6 +25,10 @@ export interface AppConfig {
     secret_hash: string;
     created_at: number;
     rate_limit: number;
+    email: string;
+    email_verified: boolean;
+    email_verification_code?: string;
+    email_verification_expires?: number;
 }
 /**
  * Result of app creation (includes plaintext secret - only shown once!)
@@ -29,7 +36,20 @@ export interface AppConfig {
 export interface CreateAppResult {
     app_id: string;
     app_secret: string;
+    email: string;
+    email_verified: boolean;
+    verification_required: boolean;
 }
+/**
+ * Public app info returned by getApp (excludes secrets and internal fields)
+ */
+export type PublicAppConfig = {
+    app_id: string;
+    created_at: number;
+    rate_limit: number;
+    email: string;
+    email_verified: boolean;
+};
 /**
  * Generate a crypto-random app ID
  * Format: 'app_' + 16 hex chars
@@ -52,6 +72,10 @@ export declare function generateAppSecret(): string;
  * @returns SHA-256 hash as hex string
  */
 export declare function hashSecret(secret: string): Promise<string>;
+/**
+ * Generate a 6-digit numeric verification code
+ */
+export declare function generateVerificationCode(): string;
 /**
  * Create a new app with crypto-random credentials
  *
@@ -60,15 +84,52 @@ export declare function hashSecret(secret: string): Promise<string>;
  * - app_secret: 'sk_' + 32 hex chars
  *
  * Stores in KV at key `app:{app_id}` with:
- * - app_id
- * - secret_hash (SHA-256, never plaintext)
- * - created_at (timestamp)
- * - rate_limit (default: 100 req/hour)
+ * - app_id, secret_hash (SHA-256), created_at, rate_limit, email, email_verified
+ *
+ * Also stores email→app_id reverse index at `email:{email}` for recovery lookups.
  *
  * @param kv - KV namespace for storage
- * @returns {app_id, app_secret} - SECRET ONLY RETURNED ONCE!
+ * @param email - Required owner email address
+ * @returns {app_id, app_secret, email, email_verified, verification_required}
+ */
+export declare function createApp(kv: KVNamespace, email: string): Promise<CreateAppResult>;
+/**
+ * Get the plaintext verification code for an app (internal use only — for sending via email).
+ *
+ * This is a separate step because createApp returns the code hash, not the plaintext.
+ * Instead, we generate and return code in createApp flow; this function regenerates
+ * a new code for resend scenarios.
  */
-export declare function createApp(kv: KVNamespace): Promise<CreateAppResult>;
+export declare function regenerateVerificationCode(kv: KVNamespace, app_id: string): Promise<{
+    code: string;
+} | null>;
+/**
+ * Verify email with the 6-digit code
+ *
+ * @returns { verified: true } on success, { verified: false, reason } on failure
+ */
+export declare function verifyEmailCode(kv: KVNamespace, app_id: string, code: string): Promise<{
+    verified: boolean;
+    reason?: string;
+}>;
+/**
+ * Look up app_id by email (for account recovery)
+ *
+ * Uses the email→app_id reverse index stored in KV.
+ * Only works for apps with verified emails.
+ */
+export declare function getAppByEmail(kv: KVNamespace, email: string): Promise<{
+    app_id: string;
+    email_verified: boolean;
+} | null>;
+/**
+ * Rotate app secret — generates a new secret and invalidates the old one.
+ *
+ * @returns New app_secret (plaintext, only returned once) or null on failure
+ */
+export declare function rotateAppSecret(kv: KVNamespace, app_id: string): Promise<{
+    app_secret: string;
+} | null>;
 /**
  * Get app configuration by app_id
  *
@@ -78,7 +139,12 @@ export declare function createApp(kv: KVNamespace): Promise<CreateAppResult>;
  * @param app_id - The app ID to retrieve
  * @returns App config (without secret_hash) or null if not found
  */
-export declare function getApp(kv: KVNamespace, app_id: string): Promise<Omit<AppConfig, 'secret_hash'> | null>;
+export declare function getApp(kv: KVNamespace, app_id: string): Promise<PublicAppConfig | null>;
+/**
+ * Get raw app config (internal use only — includes secret_hash)
+ * Used by validateAppSecret and dashboard auth.
+ */
+export declare function getAppRaw(kv: KVNamespace, app_id: string): Promise<AppConfig | null>;
 /**
  * Validate an app secret against stored hash
  *

package/dist/apps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACtF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAIF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAOtC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOhE;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAoBzE;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAC1B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,GAAG,IAAI,CAAC,CAoBhD;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CA6BlB"}
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"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"}

package/dist/apps.js

@@ -6,6 +6,9 @@
  * - SHA-256 secret hashing (never store plaintext)
  * - KV storage for app configs
  * - Rate limit tracking per app
+ * - Email verification for account recovery
+ * - Email→app_id reverse index for recovery lookups
+ * - Secret rotation with email notification
  */
 // ============ CRYPTO UTILITIES ============
 /**
@@ -51,6 +54,16 @@ export async function hashSecret(secret) {
     const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
     return hashHex;
 }
+/**
+ * Generate a 6-digit numeric verification code
+ */
+export function generateVerificationCode() {
+    const bytes = new Uint8Array(4);
+    crypto.getRandomValues(bytes);
+    // Convert to number and mod 1,000,000 to get 6 digits
+    const num = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0;
+    return (num % 1000000).toString().padStart(6, '0');
+}
 // ============ APP MANAGEMENT ============
 /**
  * Create a new app with crypto-random credentials
@@ -60,32 +73,156 @@ export async function hashSecret(secret) {
  * - app_secret: 'sk_' + 32 hex chars
  *
  * Stores in KV at key `app:{app_id}` with:
- * - app_id
- * - secret_hash (SHA-256, never plaintext)
- * - created_at (timestamp)
- * - rate_limit (default: 100 req/hour)
+ * - app_id, secret_hash (SHA-256), created_at, rate_limit, email, email_verified
+ *
+ * Also stores email→app_id reverse index at `email:{email}` for recovery lookups.
  *
  * @param kv - KV namespace for storage
- * @returns {app_id, app_secret} - SECRET ONLY RETURNED ONCE!
+ * @param email - Required owner email address
+ * @returns {app_id, app_secret, email, email_verified, verification_required}
  */
-export async function createApp(kv) {
+export async function createApp(kv, email) {
     const app_id = generateAppId();
     const app_secret = generateAppSecret();
     const secret_hash = await hashSecret(app_secret);
+    // Generate email verification code
+    const verificationCode = generateVerificationCode();
+    const verificationCodeHash = await hashSecret(verificationCode);
     const config = {
         app_id,
         secret_hash,
         created_at: Date.now(),
         rate_limit: 100, // Default: 100 requests/hour
+        email,
+        email_verified: false,
+        email_verification_code: verificationCodeHash,
+        email_verification_expires: Date.now() + 10 * 60 * 1000, // 10 minutes
     };
-    // Store in KV with key format: app:{app_id}
-    // No TTL - apps persist indefinitely unless explicitly deleted
-    await kv.put(`app:${app_id}`, JSON.stringify(config));
+    // Store app config and email→app_id index in parallel
+    await Promise.all([
+        kv.put(`app:${app_id}`, JSON.stringify(config)),
+        kv.put(`email:${email.toLowerCase()}`, app_id),
+    ]);
     return {
         app_id,
         app_secret, // ONLY returned at creation time!
+        email,
+        email_verified: false,
+        verification_required: true,
     };
 }
+/**
+ * Get the plaintext verification code for an app (internal use only — for sending via email).
+ *
+ * This is a separate step because createApp returns the code hash, not the plaintext.
+ * Instead, we generate and return code in createApp flow; this function regenerates
+ * a new code for resend scenarios.
+ */
+export async function regenerateVerificationCode(kv, app_id) {
+    try {
+        const data = await kv.get(`app:${app_id}`, 'text');
+        if (!data)
+            return null;
+        const config = JSON.parse(data);
+        if (config.email_verified)
+            return null; // Already verified
+        const code = generateVerificationCode();
+        const codeHash = await hashSecret(code);
+        config.email_verification_code = codeHash;
+        config.email_verification_expires = Date.now() + 10 * 60 * 1000;
+        await kv.put(`app:${app_id}`, JSON.stringify(config));
+        return { code };
+    }
+    catch (error) {
+        console.error(`Failed to regenerate verification code for ${app_id}:`, error);
+        return null;
+    }
+}
+/**
+ * Verify email with the 6-digit code
+ *
+ * @returns { verified: true } on success, { verified: false, reason } on failure
+ */
+export async function verifyEmailCode(kv, app_id, code) {
+    try {
+        const data = await kv.get(`app:${app_id}`, 'text');
+        if (!data) {
+            return { verified: false, reason: 'App not found' };
+        }
+        const config = JSON.parse(data);
+        if (config.email_verified) {
+            return { verified: false, reason: 'Email already verified' };
+        }
+        if (!config.email_verification_code || !config.email_verification_expires) {
+            return { verified: false, reason: 'No verification pending' };
+        }
+        if (Date.now() > config.email_verification_expires) {
+            return { verified: false, reason: 'Verification code expired' };
+        }
+        // Compare hashed codes
+        const providedHash = await hashSecret(code);
+        if (providedHash !== config.email_verification_code) {
+            return { verified: false, reason: 'Invalid verification code' };
+        }
+        // Mark email as verified, clear verification fields
+        config.email_verified = true;
+        delete config.email_verification_code;
+        delete config.email_verification_expires;
+        await kv.put(`app:${app_id}`, JSON.stringify(config));
+        return { verified: true };
+    }
+    catch (error) {
+        console.error(`Failed to verify email for ${app_id}:`, error);
+        return { verified: false, reason: 'Verification failed' };
+    }
+}
+/**
+ * Look up app_id by email (for account recovery)
+ *
+ * Uses the email→app_id reverse index stored in KV.
+ * Only works for apps with verified emails.
+ */
+export async function getAppByEmail(kv, email) {
+    try {
+        const app_id = await kv.get(`email:${email.toLowerCase()}`, 'text');
+        if (!app_id)
+            return null;
+        const data = await kv.get(`app:${app_id}`, 'text');
+        if (!data)
+            return null;
+        const config = JSON.parse(data);
+        return {
+            app_id: config.app_id,
+            email_verified: config.email_verified,
+        };
+    }
+    catch (error) {
+        console.error(`Failed to look up app by email:`, error);
+        return null;
+    }
+}
+/**
+ * Rotate app secret — generates a new secret and invalidates the old one.
+ *
+ * @returns New app_secret (plaintext, only returned once) or null on failure
+ */
+export async function rotateAppSecret(kv, app_id) {
+    try {
+        const data = await kv.get(`app:${app_id}`, 'text');
+        if (!data)
+            return null;
+        const config = JSON.parse(data);
+        const new_secret = generateAppSecret();
+        const new_hash = await hashSecret(new_secret);
+        config.secret_hash = new_hash;
+        await kv.put(`app:${app_id}`, JSON.stringify(config));
+        return { app_secret: new_secret };
+    }
+    catch (error) {
+        console.error(`Failed to rotate secret for ${app_id}:`, error);
+        return null;
+    }
+}
 /**
  * Get app configuration by app_id
  *
@@ -107,6 +244,8 @@ export async function getApp(kv, app_id) {
             app_id: config.app_id,
             created_at: config.created_at,
             rate_limit: config.rate_limit,
+            email: config.email,
+            email_verified: config.email_verified,
         };
     }
     catch (error) {
@@ -114,6 +253,22 @@ export async function getApp(kv, app_id) {
         return null;
     }
 }
+/**
+ * Get raw app config (internal use only — includes secret_hash)
+ * Used by validateAppSecret and dashboard auth.
+ */
+export async function getAppRaw(kv, app_id) {
+    try {
+        const data = await kv.get(`app:${app_id}`, 'text');
+        if (!data)
+            return null;
+        return JSON.parse(data);
+    }
+    catch (error) {
+        console.error(`Failed to get raw app ${app_id}:`, error);
+        return null;
+    }
+}
 /**
  * Validate an app secret against stored hash
  *

package/dist/challenges.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"challenges.d.ts","sourceRoot":"","sources":["../src/challenges.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"challenges.d.ts","sourceRoot":"","sources":["../src/challenges.ts"],"names":[],"mappings":"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"}

package/dist/challenges.js

@@ -120,9 +120,10 @@ export async function generateSpeedChallenge(kv, clientTimestamp, app_id) {
     };
     // Store in KV with 5 minute TTL (safety buffer for time checks)
     await storeChallenge(kv, id, challenge, 300);
+    const pipelineHint = ' Tip: compute all hashes and submit in a single HTTP request. Sequential shell commands will likely exceed the time limit.';
     const instructions = rttMs > 0
-        ? `Compute SHA256 of each number, return first 8 hex chars of each. Submit as array. You have ${adjustedTimeLimit}ms (adjusted for your ${rttMs}ms network latency).`
-        : 'Compute SHA256 of each number, return first 8 hex chars of each. Submit as array. You have 500ms.';
+        ? `Compute SHA256 of each number, return first 8 hex chars of each. Submit as array. You have ${adjustedTimeLimit}ms (adjusted for your ${rttMs}ms network latency).${pipelineHint}`
+        : `Compute SHA256 of each number, return first 8 hex chars of each. Submit as array. You have 500ms.${pipelineHint}`;
     return {
         id,
         problems,
@@ -956,8 +957,8 @@ export async function generateHybridChallenge(kv, clientTimestamp, app_id) {
         hybridChallenges.set(id, hybrid);
     }
     const instructions = speedChallenge.rttInfo
-        ? `Solve ALL speed problems (SHA256) in <${speedChallenge.timeLimit}ms (RTT-adjusted) AND answer ALL reasoning questions. Submit both together.`
-        : 'Solve ALL speed problems (SHA256) in <500ms AND answer ALL reasoning questions. Submit both together.';
+        ? `Solve ALL speed problems (SHA256) in <${speedChallenge.timeLimit}ms (RTT-adjusted) AND answer ALL reasoning questions. Submit both together. Tip: compute all hashes in-process and submit in a single HTTP request.`
+        : 'Solve ALL speed problems (SHA256) in <500ms AND answer ALL reasoning questions. Submit both together. Tip: compute all hashes in-process and submit in a single HTTP request.';
     return {
         id,
         speed: {