paygate-mcp 9.0.0 → 9.2.0

package/dist/server.js

@@ -98,6 +98,8 @@ const expiry_scanner_1 = require("./expiry-scanner");
 const key_templates_1 = require("./key-templates");
 const stripe_checkout_1 = require("./stripe-checkout");
 const backup_1 = require("./backup");
+const response_cache_1 = require("./response-cache");
+const circuit_breaker_1 = require("./circuit-breaker");
 /** Max request body size: 1MB */
 const MAX_BODY_SIZE = 1_048_576;
 /**
@@ -425,6 +427,10 @@ class PayGateServer {
     inflight = 0;
     /** Config file path for hot reload (null if not using config file) */
     configPath = null;
+    /** Response cache for tool calls (null if caching disabled) */
+    responseCache = null;
+    /** Circuit breaker for backend failure detection (null if disabled) */
+    circuitBreaker = null;
     /** The active request handler — either proxy or router */
     get handler() {
         return (this.router || this.proxy);
@@ -632,6 +638,22 @@ class PayGateServer {
                 collectEmail: stripeConfig.collectEmail,
             });
         }
+        // Response cache for tool calls (if configured)
+        const cacheTtl = this.config.cacheTtlSeconds ?? 0;
+        if (cacheTtl > 0 || Object.values(this.config.toolPricing).some(t => t.cacheTtlSeconds > 0)) {
+            this.responseCache = new response_cache_1.ResponseCache(this.config.maxCacheEntries ?? 10_000);
+            this.metrics.registerGauge('paygate_cache_entries', 'Number of cached tool call responses', () => {
+                return this.responseCache?.stats().entries ?? 0;
+            });
+        }
+        // Circuit breaker for backend failure detection (if configured)
+        const cbThreshold = this.config.circuitBreakerThreshold ?? 0;
+        if (cbThreshold > 0) {
+            this.circuitBreaker = new circuit_breaker_1.CircuitBreaker({
+                threshold: cbThreshold,
+                cooldownSeconds: this.config.circuitBreakerCooldownSeconds ?? 30,
+            });
+        }
         // Backup manager for full state snapshots
         this.backup = new backup_1.BackupManager(this.createBackupProvider());
     }
@@ -834,6 +856,12 @@ class PayGateServer {
             features.push('trusted-proxies');
         if (this.config.cors && this.config.cors.origin !== '*')
             features.push('cors-restricted');
+        if (this.responseCache)
+            features.push('response-cache');
+        if (this.circuitBreaker)
+            features.push('circuit-breaker');
+        if (this.config.toolTimeoutMs)
+            features.push(`timeout(${this.config.toolTimeoutMs}ms)`);
         const transport = this.router ? 'multi-server' : (this.proxy instanceof http_proxy_1.HttpMcpProxy ? 'http' : 'stdio');
         const keys = this.gate.store.getKeyCount?.() ?? 0;
         this.logger.info(`Listening on port ${port}`, {
@@ -883,7 +911,7 @@ class PayGateServer {
         res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
         res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, HEAD, OPTIONS');
         res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-API-Key, X-Admin-Key, Mcp-Session-Id, Authorization, X-Request-Id');
-        res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Credits-Remaining, X-Request-Id, X-PayGate-Version');
+        res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Credits-Remaining, X-Request-Id, X-PayGate-Version, X-Cache');
         if (corsConfig?.credentials) {
             res.setHeader('Access-Control-Allow-Credentials', 'true');
         }
@@ -1087,6 +1115,12 @@ class PayGateServer {
                 return this.handleKeyImport(req, res);
             case '/balance':
                 return this.handleBalance(req, res);
+            case '/balance/history':
+                return this.handleBalanceHistory(req, res);
+            case '/balance/alerts':
+                return this.handleBalanceAlerts(req, res);
+            case '/portal/rotate':
+                return this.handlePortalRotate(req, res);
             case '/limits':
                 return this.handleLimits(req, res);
             case '/usage':
@@ -1101,6 +1135,10 @@ class PayGateServer {
                 return this.handleAdminBackup(req, res);
             case '/admin/restore':
                 return this.handleAdminRestore(req, res);
+            case '/admin/cache':
+                return this.handleAdminCache(req, res);
+            case '/admin/circuit':
+                return this.handleAdminCircuit(req, res);
             case '/dashboard':
                 return this.handleDashboard(req, res);
             case '/audit':
@@ -1797,7 +1835,81 @@ class PayGateServer {
             pluginRequest = await this.plugins.executeBeforeToolCall(pluginCtx);
         }
         const toolCallStartTime = Date.now();
-        let response = await this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools);
+        let cacheHit = false;
+        let circuitBroken = false;
+        // ─── Response Cache check (before forwarding to backend) ────────
+        // response is guaranteed assigned before use: either via cache hit, circuit breaker, or handler
+        let response = null;
+        if (pluginRequest.method === 'tools/call' && this.responseCache) {
+            const toolName = pluginRequest.params?.name || '';
+            const toolArgs = pluginRequest.params?.arguments;
+            const toolPricingConfig = this.config.toolPricing[toolName];
+            const ttl = toolPricingConfig?.cacheTtlSeconds ?? this.config.cacheTtlSeconds ?? 0;
+            if (ttl > 0) {
+                const cached = this.responseCache.get(toolName, toolArgs);
+                if (cached !== undefined) {
+                    cacheHit = true;
+                    response = cached;
+                }
+            }
+        }
+        // ─── Circuit Breaker check (before forwarding to backend) ────────
+        if (!cacheHit && pluginRequest.method === 'tools/call' && this.circuitBreaker) {
+            if (!this.circuitBreaker.allowRequest()) {
+                const cbStatus = this.circuitBreaker.status();
+                circuitBroken = true;
+                response = {
+                    jsonrpc: '2.0',
+                    id: pluginRequest.id,
+                    error: {
+                        code: -32003,
+                        message: `circuit_breaker_open: Backend unavailable (${cbStatus.consecutiveFailures} consecutive failures). Retry after cooldown.`,
+                    },
+                };
+            }
+        }
+        // ─── Forward to backend (with optional timeout) ────────
+        if (!cacheHit && !circuitBroken) {
+            const toolName = pluginRequest.method === 'tools/call'
+                ? (pluginRequest.params?.name || '') : '';
+            const toolPricingConfig = toolName ? this.config.toolPricing[toolName] : undefined;
+            const timeoutMs = toolPricingConfig?.timeoutMs ?? this.config.toolTimeoutMs ?? 0;
+            if (timeoutMs > 0 && pluginRequest.method === 'tools/call') {
+                const timeoutPromise = new Promise((resolve) => {
+                    setTimeout(() => {
+                        resolve({
+                            jsonrpc: '2.0',
+                            id: pluginRequest.id,
+                            error: { code: -32004, message: `tool_timeout: ${toolName} exceeded ${timeoutMs}ms timeout` },
+                        });
+                    }, timeoutMs);
+                });
+                response = await Promise.race([
+                    this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools),
+                    timeoutPromise,
+                ]);
+            }
+            else {
+                response = await this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools);
+            }
+            // Record circuit breaker outcome
+            if (pluginRequest.method === 'tools/call' && this.circuitBreaker) {
+                if (response.error && (response.error.code === -32603 || response.error.code === -32004)) {
+                    this.circuitBreaker.recordFailure();
+                }
+                else if (!response.error || response.error.code === -32402 || response.error.code === -32001) {
+                    this.circuitBreaker.recordSuccess();
+                }
+            }
+            // Store successful responses in cache
+            if (pluginRequest.method === 'tools/call' && this.responseCache && !response.error) {
+                const cacheTtl = toolPricingConfig?.cacheTtlSeconds ?? this.config.cacheTtlSeconds ?? 0;
+                if (cacheTtl > 0) {
+                    const toolArgs = pluginRequest.params?.arguments;
+                    this.responseCache.set(toolName, toolArgs, response, cacheTtl);
+                }
+            }
+        }
         // Plugin: afterToolCall — let plugins modify the response
         if (this.plugins.count > 0 && request.method === 'tools/call') {
             const toolName = request.params?.name || '';
@@ -1910,6 +2022,10 @@ class PayGateServer {
         }
         // Build rate limit + credits headers for tools/call responses
         const rateLimitHeaders = this.buildRateLimitHeaders(apiKey, request);
+        // Add X-Cache header for tool calls when caching is active
+        if (request.method === 'tools/call' && this.responseCache) {
+            rateLimitHeaders['X-Cache'] = cacheHit ? 'HIT' : 'MISS';
+        }
         // Check if client accepts SSE
         const accept = req.headers['accept'] || '';
         const wantsSse = accept.includes('text/event-stream');
@@ -2135,6 +2251,9 @@ class PayGateServer {
                 mcp: 'POST /mcp — JSON-RPC (MCP transport). Send X-API-Key header.',
                 info: 'GET /info — Server capabilities, features, pricing summary (public)',
                 balance: 'GET /balance — Check own credits (requires X-API-Key)',
+                balanceHistory: 'GET /balance/history — Credit mutation history (requires X-API-Key)',
+                balanceAlerts: 'GET/POST /balance/alerts — Self-service low-credit alerts (requires X-API-Key)',
+                portalRotate: 'POST /portal/rotate — Self-service key rotation (requires X-API-Key)',
                 portal: 'GET /portal — Self-service API key portal (browser UI, requires X-API-Key)',
                 dashboard: 'GET /dashboard — Admin web dashboard (browser UI)',
                 ready: 'GET /ready — Readiness probe for k8s (returns 503 when draining/maintenance)',
@@ -2292,6 +2411,8 @@ class PayGateServer {
                 stripePackages: 'GET /stripe/packages — List available credit packages (public)',
                 adminBackup: 'GET /admin/backup — Full state snapshot for disaster recovery (requires X-Admin-Key, admin)',
                 adminRestore: 'POST /admin/restore — Restore state from backup snapshot (requires X-Admin-Key, admin)',
+                adminCache: 'GET /admin/cache — Response cache stats; DELETE /admin/cache?tool= — Clear cache (requires X-Admin-Key)',
+                adminCircuit: 'GET /admin/circuit — Circuit breaker status; POST /admin/circuit — Reset circuit breaker (requires X-Admin-Key)',
                 ...(this.oauth ? {
                     oauthMetadata: 'GET /.well-known/oauth-authorization-server — OAuth 2.1 server metadata',
                     oauthRegister: 'POST /oauth/register — Register OAuth client',
@@ -4460,6 +4581,184 @@ class PayGateServer {
             },
         });
     }
+    // ─── /balance/history — Self-service credit history ──────────────────────
+    handleBalanceHistory(req, res) {
+        if (req.method !== 'GET') {
+            this.sendError(res, 405, 'Method not allowed');
+            return;
+        }
+        const apiKey = req.headers['x-api-key'] || null;
+        if (!apiKey) {
+            this.sendError(res, 401, 'Missing X-API-Key header');
+            return;
+        }
+        const record = this.gate.store.getKey(apiKey);
+        if (!record || !record.active) {
+            this.sendError(res, 404, 'Invalid or inactive API key');
+            return;
+        }
+        // Parse query params
+        const url = new URL(req.url || '/', `http://localhost`);
+        const type = url.searchParams.get('type') || undefined;
+        const since = url.searchParams.get('since') || undefined;
+        const limitStr = url.searchParams.get('limit');
+        const limit = limitStr ? Math.min(200, Math.max(1, parseInt(limitStr, 10) || 50)) : 50;
+        const history = this.creditLedger.getHistory(apiKey, { type, limit, since });
+        const velocity = this.creditLedger.getSpendingVelocity(apiKey, record.credits);
+        this.sendJson(res, 200, {
+            key: (0, audit_1.maskKeyForAudit)(apiKey),
+            entries: history,
+            total: this.creditLedger.count(apiKey),
+            velocity,
+        });
+    }
+    // ─── /balance/alerts — Self-service usage alert configuration ──────────
+    selfServiceAlerts = new Map();
+    async handleBalanceAlerts(req, res) {
+        const apiKey = req.headers['x-api-key'] || null;
+        if (!apiKey) {
+            this.sendError(res, 401, 'Missing X-API-Key header');
+            return;
+        }
+        const record = this.gate.store.getKey(apiKey);
+        if (!record || !record.active) {
+            this.sendError(res, 404, 'Invalid or inactive API key');
+            return;
+        }
+        if (req.method === 'GET') {
+            const alert = this.selfServiceAlerts.get(apiKey);
+            this.sendJson(res, 200, {
+                configured: !!alert,
+                alert: alert || null,
+                currentCredits: record.credits,
+            });
+            return;
+        }
+        if (req.method === 'POST') {
+            const body = await this.readBody(req);
+            let params;
+            try {
+                params = safeJsonParse(body);
+            }
+            catch {
+                this.sendError(res, 400, 'Invalid JSON');
+                return;
+            }
+            // Validate threshold
+            const threshold = params.lowCreditThreshold;
+            if (threshold !== undefined && (typeof threshold !== 'number' || threshold < 0 || threshold > 1_000_000)) {
+                this.sendError(res, 400, 'lowCreditThreshold must be 0-1000000');
+                return;
+            }
+            // Validate webhook URL if provided (optional — alerts can work without webhook via portal polling)
+            if (params.webhookUrl !== undefined && params.webhookUrl !== null) {
+                if (typeof params.webhookUrl !== 'string' || params.webhookUrl.length > 500) {
+                    this.sendError(res, 400, 'webhookUrl must be a string under 500 chars');
+                    return;
+                }
+                // Basic URL validation — must be https
+                if (params.webhookUrl && !params.webhookUrl.startsWith('https://')) {
+                    this.sendError(res, 400, 'webhookUrl must use HTTPS');
+                    return;
+                }
+            }
+            // Handle disable
+            if (params.enabled === false) {
+                this.selfServiceAlerts.delete(apiKey);
+                this.sendJson(res, 200, { configured: false, message: 'Alert disabled' });
+                return;
+            }
+            const alert = {
+                lowCreditThreshold: threshold ?? 10,
+                webhookUrl: params.webhookUrl || null,
+                enabled: true,
+                createdAt: new Date().toISOString(),
+                lastTriggeredAt: null,
+            };
+            // Cap total alerts to prevent memory abuse
+            if (this.selfServiceAlerts.size >= 10_000 && !this.selfServiceAlerts.has(apiKey)) {
+                this.sendError(res, 429, 'Too many alert configurations');
+                return;
+            }
+            this.selfServiceAlerts.set(apiKey, alert);
+            this.sendJson(res, 200, { configured: true, alert });
+            return;
+        }
+        if (req.method === 'DELETE') {
+            this.selfServiceAlerts.delete(apiKey);
+            this.sendJson(res, 200, { configured: false, message: 'Alert removed' });
+            return;
+        }
+        this.sendError(res, 405, 'Method not allowed');
+    }
+    // ─── /portal/rotate — Self-service key rotation ─────────────────────────
+    async handlePortalRotate(req, res) {
+        if (req.method !== 'POST') {
+            this.sendError(res, 405, 'Method not allowed');
+            return;
+        }
+        const apiKey = req.headers['x-api-key'] || null;
+        if (!apiKey) {
+            this.sendError(res, 401, 'Missing X-API-Key header');
+            return;
+        }
+        const record = this.gate.store.getKey(apiKey);
+        if (!record || !record.active) {
+            this.sendError(res, 404, 'Invalid or inactive API key');
+            return;
+        }
+        // Rate limit rotation: once per 5 minutes per key (track by name to survive rotation)
+        const now = Date.now();
+        const rateKey = `rotate:${record.name || apiKey}`;
+        const lastRotation = this.selfServiceRotationTimestamps.get(rateKey);
+        if (lastRotation && now - lastRotation < 300_000) {
+            const waitSec = Math.ceil((300_000 - (now - lastRotation)) / 1000);
+            this.sendError(res, 429, `Key rotation rate limited. Try again in ${waitSec}s`);
+            return;
+        }
+        const rotated = this.gate.store.rotateKey(apiKey);
+        if (!rotated) {
+            this.sendError(res, 500, 'Key rotation failed');
+            return;
+        }
+        // Track rotation timestamp for rate limiting (by name so it persists across rotations)
+        this.selfServiceRotationTimestamps.set(rateKey, now);
+        // Clean up old timestamps (> 10 min) periodically
+        if (this.selfServiceRotationTimestamps.size > 10_000) {
+            for (const [k, ts] of this.selfServiceRotationTimestamps) {
+                if (now - ts > 600_000)
+                    this.selfServiceRotationTimestamps.delete(k);
+            }
+        }
+        // Sync to Redis if applicable
+        if (this.redisSync) {
+            this.redisSync.saveKey(rotated).catch(() => { });
+            this.redisSync.publishEvent({ type: 'key_created', key: rotated.key }).catch(() => { });
+        }
+        this.audit.log('key.rotated', (0, audit_1.maskKeyForAudit)(apiKey), `Self-service key rotation`, {
+            oldKeyMasked: (0, audit_1.maskKeyForAudit)(apiKey),
+            newKeyMasked: (0, audit_1.maskKeyForAudit)(rotated.key),
+            source: 'portal',
+        });
+        this.emitWebhookAdmin('key.rotated', (0, audit_1.maskKeyForAudit)(apiKey), {
+            oldKeyMasked: (0, audit_1.maskKeyForAudit)(apiKey),
+            newKeyMasked: (0, audit_1.maskKeyForAudit)(rotated.key),
+            source: 'portal',
+        });
+        // Migrate self-service alerts to new key
+        const alertConfig = this.selfServiceAlerts.get(apiKey);
+        if (alertConfig) {
+            this.selfServiceAlerts.delete(apiKey);
+            this.selfServiceAlerts.set(rotated.key, alertConfig);
+        }
+        this.sendJson(res, 200, {
+            message: 'Key rotated successfully',
+            newKey: rotated.key,
+            name: rotated.name,
+            credits: rotated.credits,
+        });
+    }
+    selfServiceRotationTimestamps = new Map();
     // ─── /limits — Set spending limit ────────────────────────────────────────
     async handleLimits(req, res) {
         if (req.method !== 'POST') {
@@ -4709,6 +5008,60 @@ class PayGateServer {
         this.audit.log('admin.backup_restored', 'admin', `State restored from backup (mode: ${mode})`, { mode, results: result.results, warnings: result.warnings });
         this.sendJson(res, result.success ? 200 : 207, result);
     }
+    // ─── /admin/cache — Response cache management ─────────────────────────────
+    handleAdminCache(req, res) {
+        if (req.method === 'GET') {
+            if (!this.checkAdmin(req, res, 'viewer'))
+                return;
+            if (!this.responseCache) {
+                this.sendJson(res, 200, { enabled: false, message: 'Response caching is not enabled' });
+                return;
+            }
+            this.sendJson(res, 200, { enabled: true, ...this.responseCache.stats() });
+            return;
+        }
+        if (req.method === 'DELETE') {
+            if (!this.checkAdmin(req, res, 'admin'))
+                return;
+            if (!this.responseCache) {
+                this.sendJson(res, 200, { enabled: false, cleared: 0 });
+                return;
+            }
+            const url = new URL(req.url || '/', `http://localhost`);
+            const tool = url.searchParams.get('tool') || undefined;
+            const cleared = this.responseCache.clear(tool);
+            this.audit.log('admin.cache_cleared', 'admin', `Cache cleared${tool ? ` for tool: ${tool}` : ''}`, { tool, cleared });
+            this.sendJson(res, 200, { cleared, tool: tool || null });
+            return;
+        }
+        this.sendError(res, 405, 'Method not allowed. Use GET or DELETE.');
+    }
+    // ─── /admin/circuit — Circuit breaker status and management ───────────────
+    handleAdminCircuit(req, res) {
+        if (req.method === 'GET') {
+            if (!this.checkAdmin(req, res, 'viewer'))
+                return;
+            if (!this.circuitBreaker) {
+                this.sendJson(res, 200, { enabled: false, message: 'Circuit breaker is not enabled' });
+                return;
+            }
+            this.sendJson(res, 200, { enabled: true, ...this.circuitBreaker.status() });
+            return;
+        }
+        if (req.method === 'POST') {
+            if (!this.checkAdmin(req, res, 'admin'))
+                return;
+            if (!this.circuitBreaker) {
+                this.sendJson(res, 200, { enabled: false, message: 'Circuit breaker is not enabled' });
+                return;
+            }
+            this.circuitBreaker.reset();
+            this.audit.log('admin.circuit_reset', 'admin', 'Circuit breaker manually reset to closed state');
+            this.sendJson(res, 200, { reset: true, ...this.circuitBreaker.status() });
+            return;
+        }
+        this.sendError(res, 405, 'Method not allowed. Use GET or POST.');
+    }
     // ─── /dashboard — Admin web dashboard ─────────────────────────────────────
     handleDashboard(_req, res) {
         // Dashboard is public HTML — auth is done client-side via admin key prompt.