@dupecom/botcha-cloudflare 0.3.3 → 0.9.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":"AAAA;;;;GAIG;AAGH,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,EAAE,CAAC,IAAI,EAAE;QACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,KAAK,IAAI,CAAC;CACZ,CAAC;AAEF,MAAM,WAAW,cAAc;IAE7B,SAAS,EAAE,qBAAqB,GAAG,oBAAoB,GAAG,cAAc,GAAG,cAAc,GAAG,qBAAqB,GAAG,OAAO,CAAC;IAG5H,aAAa,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,kBAAkB,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC3C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAG5B,UAAU,CAAC,EAAE,eAAe,GAAG,cAAc,GAAG,MAAM,CAAC;IAGvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IAGxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,aAAa,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,EAC5D,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,aAAa,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,EAC5D,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,UAAU,EAAE,eAAe,GAAG,cAAc,EAC5C,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,GAAG,SAAS,EAC7C,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAQf"}

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,93 @@
+/**
+ * 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
+ */
+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;
+}
+/**
+ * Result of app creation (includes plaintext secret - only shown once!)
+ */
+export interface CreateAppResult {
+    app_id: string;
+    app_secret: string;
+}
+/**
+ * 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>;
+/**
+ * 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, never plaintext)
+ * - created_at (timestamp)
+ * - rate_limit (default: 100 req/hour)
+ *
+ * @param kv - KV namespace for storage
+ * @returns {app_id, app_secret} - SECRET ONLY RETURNED ONCE!
+ */
+export declare function createApp(kv: KVNamespace): Promise<CreateAppResult>;
+/**
+ * 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<Omit<AppConfig, 'secret_hash'> | 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":"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"}

package/dist/apps.js

@@ -0,0 +1,152 @@
+/**
+ * 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
+ */
+// ============ 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;
+}
+// ============ 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, never plaintext)
+ * - created_at (timestamp)
+ * - rate_limit (default: 100 req/hour)
+ *
+ * @param kv - KV namespace for storage
+ * @returns {app_id, app_secret} - SECRET ONLY RETURNED ONCE!
+ */
+export async function createApp(kv) {
+    const app_id = generateAppId();
+    const app_secret = generateAppSecret();
+    const secret_hash = await hashSecret(app_secret);
+    const config = {
+        app_id,
+        secret_hash,
+        created_at: Date.now(),
+        rate_limit: 100, // Default: 100 requests/hour
+    };
+    // 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));
+    return {
+        app_id,
+        app_secret, // ONLY returned at creation time!
+    };
+}
+/**
+ * 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,
+        };
+    }
+    catch (error) {
+        console.error(`Failed to get 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;
+    }
+}

package/dist/auth.d.ts

@@ -1,26 +1,113 @@
 /**
  * BOTCHA Authentication & JWT Token Management
  *
- * Token-based auth flow for production API access
+ * Token-based auth flow with security features:
+ * - JTI (JWT ID) for revocation
+ * - Audience claims for API scoping
+ * - Client IP binding for additional security
+ * - Short-lived access tokens (5 min) with refresh tokens (1 hour)
+ * - Token revocation via KV storage
  */
 /**
- * JWT payload structure
+ * KV namespace interface (Cloudflare Workers)
+ */
+export interface KVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * JWT payload structure for access tokens
  */
 export interface BotchaTokenPayload {
     sub: string;
     iat: number;
     exp: number;
+    jti: string;
     type: 'botcha-verified';
     solveTime: number;
+    aud?: string;
+    client_ip?: string;
+    app_id?: string;
+}
+/**
+ * JWT payload structure for refresh tokens
+ */
+export interface BotchaRefreshTokenPayload {
+    sub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    type: 'botcha-refresh';
+    solveTime: number;
+    app_id?: string;
+}
+/**
+ * Token creation result
+ */
+export interface TokenCreationResult {
+    access_token: string;
+    expires_in: number;
+    refresh_token: string;
+    refresh_expires_in: number;
 }
 /**
- * Generate a JWT token after successful challenge verification
+ * Token generation options
  */
-export declare function generateToken(challengeId: string, solveTimeMs: number, secret: string): Promise<string>;
+export interface TokenGenerationOptions {
+    aud?: string;
+    clientIp?: string;
+    app_id?: string;
+}
+/**
+ * Generate JWT tokens (access + refresh) after successful challenge verification
+ *
+ * Access token: 5 minutes, used for API access
+ * Refresh token: 1 hour, used to get new access tokens
+ */
+export declare function generateToken(challengeId: string, solveTimeMs: number, secret: string, env?: {
+    CHALLENGES: KVNamespace;
+}, options?: TokenGenerationOptions): Promise<TokenCreationResult>;
+/**
+ * Revoke a token by its JTI
+ *
+ * Stores the JTI in the revocation list (KV) with 1 hour TTL
+ */
+export declare function revokeToken(jti: string, env: {
+    CHALLENGES: KVNamespace;
+}): Promise<void>;
 /**
- * Verify a JWT token
+ * Refresh an access token using a valid refresh token
+ *
+ * Verifies the refresh token, checks revocation, and issues a new access token
+ */
+export declare function refreshAccessToken(refreshToken: string, env: {
+    CHALLENGES: KVNamespace;
+}, secret: string, options?: TokenGenerationOptions): Promise<{
+    success: boolean;
+    tokens?: Omit<TokenCreationResult, 'refresh_token' | 'refresh_expires_in'> & {
+        access_token: string;
+        expires_in: number;
+    };
+    error?: string;
+}>;
+/**
+ * Verify a JWT token with security checks
+ *
+ * Checks:
+ * - Token signature and expiry
+ * - Revocation status (via JTI)
+ * - Audience claim (if provided)
+ * - Client IP binding (if provided)
  */
-export declare function verifyToken(token: string, secret: string): Promise<{
+export declare function verifyToken(token: string, secret: string, env?: {
+    CHALLENGES: KVNamespace;
+}, options?: {
+    requiredAud?: string;
+    clientIp?: string;
+}): Promise<{
     valid: boolean;
     payload?: BotchaTokenPayload;
     error?: string;

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAejB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrE"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAmF9B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,GAC/B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,GAAG,oBAAoB,CAAC,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0G1K;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6E3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrE"}