@dupecom/botcha-cloudflare 0.3.3 → 0.10.0

package/dist/analytics.d.ts

@@ -0,0 +1,60 @@
+/**
+ * BOTCHA Analytics Engine Integration
+ *
+ * Tracks usage metrics for business intelligence and monitoring
+ */
+export type AnalyticsEngineDataset = {
+    writeDataPoint: (data: {
+        blobs?: string[];
+        doubles?: number[];
+        indexes?: string[];
+    }) => void;
+};
+export interface AnalyticsEvent {
+    eventType: 'challenge_generated' | 'challenge_verified' | 'auth_success' | 'auth_failure' | 'rate_limit_exceeded' | 'error';
+    challengeType?: 'speed' | 'standard' | 'reasoning' | 'hybrid';
+    endpoint?: string;
+    verificationResult?: 'success' | 'failure';
+    verificationReason?: string;
+    authMethod?: 'landing-token' | 'bearer-token' | 'none';
+    solveTimeMs?: number;
+    responseTimeMs?: number;
+    clientIP?: string;
+    userAgent?: string;
+    country?: string;
+    errorType?: string;
+    errorMessage?: string;
+}
+/**
+ * Log an analytics event to Cloudflare Analytics Engine
+ */
+export declare function logAnalyticsEvent(analytics: AnalyticsEngineDataset | undefined, event: AnalyticsEvent): Promise<void>;
+/**
+ * Extract country from Cloudflare headers
+ */
+export declare function getCountry(request: Request): string;
+/**
+ * Extract user agent
+ */
+export declare function getUserAgent(request: Request): string;
+/**
+ * Helper to track challenge generation
+ */
+export declare function trackChallengeGenerated(analytics: AnalyticsEngineDataset | undefined, challengeType: 'speed' | 'standard' | 'reasoning' | 'hybrid', endpoint: string, request: Request, clientIP: string, responseTimeMs: number): Promise<void>;
+/**
+ * Helper to track challenge verification
+ */
+export declare function trackChallengeVerified(analytics: AnalyticsEngineDataset | undefined, challengeType: 'speed' | 'standard' | 'reasoning' | 'hybrid', endpoint: string, success: boolean, solveTimeMs: number | undefined, reason: string | undefined, request: Request, clientIP: string): Promise<void>;
+/**
+ * Helper to track authentication attempts
+ */
+export declare function trackAuthAttempt(analytics: AnalyticsEngineDataset | undefined, authMethod: 'landing-token' | 'bearer-token', success: boolean, endpoint: string, request: Request, clientIP: string): Promise<void>;
+/**
+ * Helper to track rate limit exceeded
+ */
+export declare function trackRateLimitExceeded(analytics: AnalyticsEngineDataset | undefined, endpoint: string, request: Request, clientIP: string): Promise<void>;
+/**
+ * Helper to track errors
+ */
+export declare function trackError(analytics: AnalyticsEngineDataset | undefined, errorType: string, errorMessage: string, endpoint: string, request: Request): Promise<void>;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

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

package/dist/analytics.js

@@ -0,0 +1,130 @@
+/**
+ * BOTCHA Analytics Engine Integration
+ *
+ * Tracks usage metrics for business intelligence and monitoring
+ */
+/**
+ * Log an analytics event to Cloudflare Analytics Engine
+ */
+export async function logAnalyticsEvent(analytics, event) {
+    if (!analytics) {
+        // Analytics not configured (local dev)
+        return;
+    }
+    try {
+        // Cloudflare Analytics Engine uses:
+        // - blobs: string[] (up to 20 strings, max 5120 chars total)
+        // - doubles: number[] (up to 20 numbers)
+        // - indexes: string[] (up to 20 strings for filtering, each max 96 bytes)
+        const blobs = [
+            event.eventType,
+            event.challengeType || '',
+            event.endpoint || '',
+            event.verificationResult || '',
+            event.authMethod || '',
+            event.clientIP || '',
+            event.country || '',
+            event.errorType || '',
+        ];
+        const doubles = [
+            event.solveTimeMs || 0,
+            event.responseTimeMs || 0,
+        ];
+        const indexes = [
+            event.eventType,
+            event.challengeType || 'none',
+            event.endpoint || 'unknown',
+        ];
+        analytics.writeDataPoint({
+            blobs,
+            doubles,
+            indexes,
+        });
+    }
+    catch (error) {
+        // Never throw on analytics failures
+        console.error('Analytics logging failed:', error);
+    }
+}
+/**
+ * Extract country from Cloudflare headers
+ */
+export function getCountry(request) {
+    return request.headers.get('cf-ipcountry') || 'unknown';
+}
+/**
+ * Extract user agent
+ */
+export function getUserAgent(request) {
+    const ua = request.headers.get('user-agent') || 'unknown';
+    // Truncate to 100 chars to avoid bloating analytics
+    return ua.substring(0, 100);
+}
+/**
+ * Helper to track challenge generation
+ */
+export async function trackChallengeGenerated(analytics, challengeType, endpoint, request, clientIP, responseTimeMs) {
+    await logAnalyticsEvent(analytics, {
+        eventType: 'challenge_generated',
+        challengeType,
+        endpoint,
+        clientIP,
+        country: getCountry(request),
+        userAgent: getUserAgent(request),
+        responseTimeMs,
+    });
+}
+/**
+ * Helper to track challenge verification
+ */
+export async function trackChallengeVerified(analytics, challengeType, endpoint, success, solveTimeMs, reason, request, clientIP) {
+    await logAnalyticsEvent(analytics, {
+        eventType: 'challenge_verified',
+        challengeType,
+        endpoint,
+        verificationResult: success ? 'success' : 'failure',
+        verificationReason: reason,
+        solveTimeMs,
+        clientIP,
+        country: getCountry(request),
+        userAgent: getUserAgent(request),
+    });
+}
+/**
+ * Helper to track authentication attempts
+ */
+export async function trackAuthAttempt(analytics, authMethod, success, endpoint, request, clientIP) {
+    await logAnalyticsEvent(analytics, {
+        eventType: success ? 'auth_success' : 'auth_failure',
+        authMethod,
+        endpoint,
+        verificationResult: success ? 'success' : 'failure',
+        clientIP,
+        country: getCountry(request),
+        userAgent: getUserAgent(request),
+    });
+}
+/**
+ * Helper to track rate limit exceeded
+ */
+export async function trackRateLimitExceeded(analytics, endpoint, request, clientIP) {
+    await logAnalyticsEvent(analytics, {
+        eventType: 'rate_limit_exceeded',
+        endpoint,
+        clientIP,
+        country: getCountry(request),
+        userAgent: getUserAgent(request),
+    });
+}
+/**
+ * Helper to track errors
+ */
+export async function trackError(analytics, errorType, errorMessage, endpoint, request) {
+    await logAnalyticsEvent(analytics, {
+        eventType: 'error',
+        errorType,
+        errorMessage: errorMessage.substring(0, 200), // Truncate
+        endpoint,
+        country: getCountry(request),
+    });
+}

package/dist/apps.d.ts

@@ -0,0 +1,159 @@
+/**
+ * BOTCHA App Management & Multi-Tenant Infrastructure
+ *
+ * Secure app creation with:
+ * - Crypto-random app IDs and secrets
+ * - 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>;
+    put: (key: string, value: string, options?: {
+        expirationTtl?: number;
+    }) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+};
+/**
+ * App configuration stored in KV
+ */
+export interface AppConfig {
+    app_id: string;
+    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!)
+ */
+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
+ *
+ * Example: app_a1b2c3d4e5f6a7b8
+ */
+export declare function generateAppId(): string;
+/**
+ * Generate a crypto-random app secret
+ * Format: 'sk_' + 32 hex chars
+ *
+ * Example: sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
+ */
+export declare function generateAppSecret(): string;
+/**
+ * Hash a secret using SHA-256
+ * Returns hex-encoded hash string
+ *
+ * @param secret - The plaintext secret to hash
+ * @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
+ *
+ * Generates:
+ * - app_id: 'app_' + 16 hex chars
+ * - app_secret: 'sk_' + 32 hex chars
+ *
+ * Stores in KV at key `app:{app_id}` with:
+ * - 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
+ * @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 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
+ *
+ * Returns app config WITHOUT secret_hash for security
+ *
+ * @param kv - KV namespace
+ * @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<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
+ *
+ * Uses constant-time comparison to prevent timing attacks
+ *
+ * @param kv - KV namespace
+ * @param app_id - The app ID
+ * @param app_secret - The plaintext secret to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function validateAppSecret(kv: KVNamespace, app_id: string, app_secret: string): Promise<boolean>;
+//# sourceMappingURL=apps.d.ts.map

package/dist/apps.d.ts.map

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

package/dist/apps.js

@@ -0,0 +1,307 @@
+/**
+ * BOTCHA App Management & Multi-Tenant Infrastructure
+ *
+ * Secure app creation with:
+ * - Crypto-random app IDs and secrets
+ * - 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 ============
+/**
+ * Generate a crypto-random app ID
+ * Format: 'app_' + 16 hex chars
+ *
+ * Example: app_a1b2c3d4e5f6a7b8
+ */
+export function generateAppId() {
+    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 `app_${hexString}`;
+}
+/**
+ * Generate a crypto-random app secret
+ * Format: 'sk_' + 32 hex chars
+ *
+ * Example: sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
+ */
+export function generateAppSecret() {
+    const bytes = new Uint8Array(16); // 16 bytes = 32 hex chars
+    crypto.getRandomValues(bytes);
+    const hexString = Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+    return `sk_${hexString}`;
+}
+/**
+ * Hash a secret using SHA-256
+ * Returns hex-encoded hash string
+ *
+ * @param secret - The plaintext secret to hash
+ * @returns SHA-256 hash as hex string
+ */
+export async function hashSecret(secret) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(secret);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    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
+ *
+ * Generates:
+ * - app_id: 'app_' + 16 hex chars
+ * - app_secret: 'sk_' + 32 hex chars
+ *
+ * Stores in KV at key `app:{app_id}` with:
+ * - 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
+ * @param email - Required owner email address
+ * @returns {app_id, app_secret, email, email_verified, verification_required}
+ */
+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 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
+ *
+ * Returns app config WITHOUT secret_hash for security
+ *
+ * @param kv - KV namespace
+ * @param app_id - The app ID to retrieve
+ * @returns App config (without secret_hash) or null if not found
+ */
+export async function getApp(kv, app_id) {
+    try {
+        const data = await kv.get(`app:${app_id}`, 'text');
+        if (!data) {
+            return null;
+        }
+        const config = JSON.parse(data);
+        // Return config WITHOUT secret_hash (security)
+        return {
+            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) {
+        console.error(`Failed to get app ${app_id}:`, error);
+        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
+ *
+ * Uses constant-time comparison to prevent timing attacks
+ *
+ * @param kv - KV namespace
+ * @param app_id - The app ID
+ * @param app_secret - The plaintext secret to validate
+ * @returns true if valid, false otherwise
+ */
+export async function validateAppSecret(kv, app_id, app_secret) {
+    try {
+        const data = await kv.get(`app:${app_id}`, 'text');
+        if (!data) {
+            return false;
+        }
+        const config = JSON.parse(data);
+        const providedHash = await hashSecret(app_secret);
+        // Constant-time comparison to prevent timing attacks
+        // Compare each character to avoid early exit
+        if (providedHash.length !== config.secret_hash.length) {
+            return false;
+        }
+        let isValid = true;
+        for (let i = 0; i < providedHash.length; i++) {
+            if (providedHash[i] !== config.secret_hash[i]) {
+                isValid = false;
+            }
+        }
+        return isValid;
+    }
+    catch (error) {
+        console.error(`Failed to validate app secret for ${app_id}:`, error);
+        return false;
+    }
+}