paygate-mcp 9.2.0 → 9.4.0

package/dist/server.js

@@ -100,6 +100,8 @@ 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");
+const compliance_1 = require("./compliance");
+const guardrails_1 = require("./guardrails");
 /** Max request body size: 1MB */
 const MAX_BODY_SIZE = 1_048_576;
 /**
@@ -431,6 +433,8 @@ class PayGateServer {
     responseCache = null;
     /** Circuit breaker for backend failure detection (null if disabled) */
     circuitBreaker = null;
+    /** Content guardrails for PII detection and content policy enforcement. */
+    guardrails;
     /** The active request handler — either proxy or router */
     get handler() {
         return (this.router || this.proxy);
@@ -654,6 +658,12 @@ class PayGateServer {
                 cooldownSeconds: this.config.circuitBreakerCooldownSeconds ?? 30,
             });
         }
+        // Content guardrails for PII detection
+        this.guardrails = new guardrails_1.ContentGuardrails({
+            enabled: this.config.guardrails?.enabled ?? false,
+            includeContext: this.config.guardrails?.includeContext ?? false,
+            maxViolations: this.config.guardrails?.maxViolations ?? 10_000,
+        });
         // Backup manager for full state snapshots
         this.backup = new backup_1.BackupManager(this.createBackupProvider());
     }
@@ -911,7 +921,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, X-Cache');
+        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, X-Output-Surcharge');
         if (corsConfig?.credentials) {
             res.setHeader('Access-Control-Allow-Credentials', 'true');
         }
@@ -1109,6 +1119,8 @@ class PayGateServer {
                 return this.handleCreditTransfer(req, res);
             case '/keys/bulk':
                 return this.handleBulkOperations(req, res);
+            case '/keys/webhook':
+                return this.handleKeyWebhook(req, res);
             case '/keys/export':
                 return this.handleKeyExport(req, res);
             case '/keys/import':
@@ -1380,6 +1392,17 @@ class PayGateServer {
                     return this.handleComplianceReport(req, res);
                 this.sendError(res, 405, 'Method not allowed. Use GET.');
                 return;
+            case '/admin/compliance/export':
+                if (req.method === 'GET')
+                    return this.handleComplianceExport(req, res);
+                this.sendError(res, 405, 'Method not allowed. Use GET.');
+                return;
+            case '/admin/guardrails':
+                return this.handleGuardrails(req, res);
+            case '/admin/guardrails/violations':
+                return this.handleGuardrailViolations(req, res);
+            case '/keys/geo':
+                return this.handleKeyGeo(req, res);
             case '/admin/sla':
                 if (req.method === 'GET')
                     return this.handleSlaMonitoring(req, res);
@@ -1765,6 +1788,9 @@ class PayGateServer {
         }
         // Extract client IP for IP allowlist checking (trusted proxy-aware)
         const clientIp = resolveClientIp(req, this.config.trustedProxies);
+        // Extract country code from reverse proxy header (Cloudflare, AWS, etc.)
+        const geoHeader = this.config.geoCountryHeader || 'X-Country';
+        const countryCode = req.headers[geoHeader.toLowerCase()] || undefined;
         // Extract scoped token tool restrictions (set by resolveApiKey)
         const scopedTokenTools = req._scopedTokenTools;
         // ─── Batch tool calls ────────────────────────────────────────────────
@@ -1782,7 +1808,7 @@ class PayGateServer {
                 res.end(JSON.stringify(errResp));
                 return;
             }
-            const batchResponse = await this.handler.handleBatchRequest(calls, request.id, apiKey, clientIp, scopedTokenTools);
+            const batchResponse = await this.handler.handleBatchRequest(calls, request.id, apiKey, clientIp, scopedTokenTools, countryCode);
             // Audit + metrics for batch
             if (batchResponse.error) {
                 this.audit.log('gate.deny', (0, audit_1.maskKeyForAudit)(apiKey || 'anonymous'), `Batch denied (${calls.length} calls)`, {
@@ -1837,6 +1863,38 @@ class PayGateServer {
         const toolCallStartTime = Date.now();
         let cacheHit = false;
         let circuitBroken = false;
+        // ─── Content Guardrails: scan inputs ────────────────────────────
+        if (this.guardrails.isEnabled && pluginRequest.method === 'tools/call') {
+            const grToolName = pluginRequest.params?.name || '';
+            const grToolArgs = pluginRequest.params?.arguments;
+            const inputContent = grToolArgs ? JSON.stringify(grToolArgs) : '';
+            if (inputContent) {
+                const grResult = this.guardrails.check(inputContent, grToolName, 'input', apiKey ? apiKey.slice(0, 10) : 'anon');
+                if (grResult.blocked) {
+                    const ruleNames = grResult.violations.filter(v => v.action === 'block').map(v => v.ruleName).join(', ');
+                    this.audit.log('guardrail.block', (0, audit_1.maskKeyForAudit)(apiKey || 'anonymous'), `Input blocked by guardrail: ${ruleNames}`, { tool: grToolName, scope: 'input', requestId });
+                    const errResp = {
+                        jsonrpc: '2.0',
+                        id: pluginRequest.id,
+                        error: { code: -32406, message: `Content policy violation: input blocked by guardrail (${ruleNames})` },
+                    };
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'Mcp-Session-Id': sessionId });
+                    res.end(JSON.stringify(errResp));
+                    return;
+                }
+                if (grResult.redactedContent && grToolArgs) {
+                    // Replace arguments with redacted version
+                    try {
+                        pluginRequest.params.arguments = JSON.parse(grResult.redactedContent);
+                    }
+                    catch { /* ignore parse error, use original */ }
+                }
+                // Add warnings as response headers
+                for (const warning of grResult.warnings) {
+                    res.setHeader('X-Guardrail-Warning', warning);
+                }
+            }
+        }
         // ─── Response Cache check (before forwarding to backend) ────────
         // response is guaranteed assigned before use: either via cache hit, circuit breaker, or handler
         let response = null;
@@ -1885,12 +1943,12 @@ class PayGateServer {
                     }, timeoutMs);
                 });
                 response = await Promise.race([
-                    this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools),
+                    this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools, countryCode),
                     timeoutPromise,
                 ]);
             }
             else {
-                response = await this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools);
+                response = await this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools, countryCode);
             }
             // Record circuit breaker outcome
             if (pluginRequest.method === 'tools/call' && this.circuitBreaker) {
@@ -1910,6 +1968,64 @@ class PayGateServer {
                 }
             }
         }
+        // ─── Outcome-based pricing: post-call output surcharge ────────
+        let outputSurcharge = 0;
+        if (!cacheHit && !circuitBroken && request.method === 'tools/call' && response && !response.error && apiKey) {
+            const toolName = request.params?.name || '';
+            const toolPricingForOutput = this.config.toolPricing[toolName];
+            const creditsPerKbOutput = toolPricingForOutput?.creditsPerKbOutput ?? 0;
+            if (creditsPerKbOutput > 0) {
+                const outputBytes = Buffer.byteLength(JSON.stringify(response.result ?? ''), 'utf-8');
+                const outputKb = outputBytes / 1024;
+                outputSurcharge = Math.ceil(outputKb * creditsPerKbOutput);
+                if (outputSurcharge > 0) {
+                    const keyRecord = this.gate.store.getKey(apiKey);
+                    if (keyRecord && keyRecord.credits >= outputSurcharge) {
+                        this.gate.store.deductCredits(apiKey, outputSurcharge);
+                        keyRecord.totalSpent += outputSurcharge;
+                        this.gate.store.save();
+                        this.gate.onCreditsDeducted?.(apiKey, outputSurcharge);
+                    }
+                    else if (keyRecord) {
+                        // Insufficient credits for output surcharge — deduct what's available
+                        const available = keyRecord.credits;
+                        if (available > 0) {
+                            this.gate.store.deductCredits(apiKey, available);
+                            keyRecord.totalSpent += available;
+                            this.gate.store.save();
+                            this.gate.onCreditsDeducted?.(apiKey, available);
+                        }
+                        outputSurcharge = available;
+                    }
+                }
+            }
+        }
+        // ─── Content Guardrails: scan outputs ────────────────────────────
+        if (this.guardrails.isEnabled && request.method === 'tools/call' && response && !response.error) {
+            const grToolName = request.params?.name || '';
+            const outputContent = response.result ? JSON.stringify(response.result) : '';
+            if (outputContent) {
+                const grResult = this.guardrails.check(outputContent, grToolName, 'output', apiKey ? apiKey.slice(0, 10) : 'anon');
+                if (grResult.blocked) {
+                    const ruleNames = grResult.violations.filter(v => v.action === 'block').map(v => v.ruleName).join(', ');
+                    this.audit.log('guardrail.block', (0, audit_1.maskKeyForAudit)(apiKey || 'anonymous'), `Output blocked by guardrail: ${ruleNames}`, { tool: grToolName, scope: 'output', requestId });
+                    response = {
+                        jsonrpc: '2.0',
+                        id: response.id,
+                        error: { code: -32406, message: `Content policy violation: output blocked by guardrail (${ruleNames})` },
+                    };
+                }
+                else if (grResult.redactedContent) {
+                    try {
+                        response = { ...response, result: JSON.parse(grResult.redactedContent) };
+                    }
+                    catch { /* ignore parse error, use original */ }
+                }
+                for (const warning of grResult.warnings) {
+                    res.setHeader('X-Guardrail-Warning', warning);
+                }
+            }
+        }
         // Plugin: afterToolCall — let plugins modify the response
         if (this.plugins.count > 0 && request.method === 'tools/call') {
             const toolName = request.params?.name || '';
@@ -2026,6 +2142,10 @@ class PayGateServer {
         if (request.method === 'tools/call' && this.responseCache) {
             rateLimitHeaders['X-Cache'] = cacheHit ? 'HIT' : 'MISS';
         }
+        // Add X-Output-Surcharge header for outcome-based pricing
+        if (request.method === 'tools/call' && outputSurcharge > 0) {
+            rateLimitHeaders['X-Output-Surcharge'] = String(outputSurcharge);
+        }
         // Check if client accepts SSE
         const accept = req.headers['accept'] || '';
         const wantsSse = accept.includes('text/event-stream');
@@ -2413,6 +2533,11 @@ class PayGateServer {
                 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)',
+                adminComplianceExport: 'GET /admin/compliance/export?framework=soc2|gdpr|hipaa&format=json|csv — Framework-specific compliance audit export with event classification (requires X-Admin-Key)',
+                keyWebhook: 'POST /keys/webhook — Set per-key webhook URL; DELETE /keys/webhook — Remove per-key webhook (requires X-Admin-Key)',
+                adminGuardrails: 'GET /admin/guardrails — View guardrail rules and stats; POST /admin/guardrails — Toggle, upsert rule, or import rules; DELETE /admin/guardrails?id= — Remove rule (requires X-Admin-Key)',
+                adminGuardrailViolations: 'GET /admin/guardrails/violations — View content policy violations with filters; DELETE — Clear all violations (requires X-Admin-Key)',
+                keyGeo: 'POST /keys/geo — Set per-key country restrictions; GET /keys/geo?key= — View geo restrictions; DELETE /keys/geo?key= — Clear restrictions (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',
@@ -3044,6 +3169,54 @@ class PayGateServer {
                         });
                         break;
                     }
+                    case 'suspend': {
+                        const key = op.key;
+                        if (!key) {
+                            results.push({ index: i, action: 'suspend', success: false, error: 'Missing key' });
+                            break;
+                        }
+                        const rec = this.gate.store.getKey(key);
+                        if (!rec) {
+                            results.push({ index: i, action: 'suspend', success: false, error: 'Key not found' });
+                            break;
+                        }
+                        if (rec.suspended) {
+                            results.push({ index: i, action: 'suspend', success: true, result: { keyMasked: (0, audit_1.maskKeyForAudit)(key), alreadySuspended: true } });
+                            break;
+                        }
+                        rec.suspended = true;
+                        this.gate.store.save();
+                        if (this.redisSync)
+                            this.redisSync.saveKey(rec).catch(() => { });
+                        this.audit.log('key.suspended', 'admin', 'Key suspended (bulk)', { keyMasked: (0, audit_1.maskKeyForAudit)(key) });
+                        this.emitWebhookAdmin('key.suspended', 'admin', { keyMasked: (0, audit_1.maskKeyForAudit)(key) });
+                        results.push({ index: i, action: 'suspend', success: true, result: { keyMasked: (0, audit_1.maskKeyForAudit)(key) } });
+                        break;
+                    }
+                    case 'resume': {
+                        const key = op.key;
+                        if (!key) {
+                            results.push({ index: i, action: 'resume', success: false, error: 'Missing key' });
+                            break;
+                        }
+                        const rec = this.gate.store.getKey(key);
+                        if (!rec) {
+                            results.push({ index: i, action: 'resume', success: false, error: 'Key not found' });
+                            break;
+                        }
+                        if (!rec.suspended) {
+                            results.push({ index: i, action: 'resume', success: true, result: { keyMasked: (0, audit_1.maskKeyForAudit)(key), alreadyActive: true } });
+                            break;
+                        }
+                        rec.suspended = false;
+                        this.gate.store.save();
+                        if (this.redisSync)
+                            this.redisSync.saveKey(rec).catch(() => { });
+                        this.audit.log('key.resumed', 'admin', 'Key resumed (bulk)', { keyMasked: (0, audit_1.maskKeyForAudit)(key) });
+                        this.emitWebhookAdmin('key.resumed', 'admin', { keyMasked: (0, audit_1.maskKeyForAudit)(key) });
+                        results.push({ index: i, action: 'resume', success: true, result: { keyMasked: (0, audit_1.maskKeyForAudit)(key) } });
+                        break;
+                    }
                     default:
                         results.push({ index: i, action: op.action || 'unknown', success: false, error: `Unknown action: ${op.action}` });
                 }
@@ -3063,6 +3236,116 @@ class PayGateServer {
         });
     }
     // ─── /keys/export — Export all API keys for backup ────────────────────────
+    // ─── /keys/webhook — Per-key webhook URL management ────────────────────────
+    async handleKeyWebhook(req, res) {
+        if (!this.checkAdmin(req, res))
+            return;
+        if (req.method === 'POST') {
+            // Set per-key webhook URL
+            const body = await this.readBody(req);
+            let params;
+            try {
+                params = JSON.parse(body);
+            }
+            catch {
+                this.sendError(res, 400, 'Invalid JSON');
+                return;
+            }
+            const apiKeyPrefix = params.apiKey;
+            const webhookUrl = params.webhookUrl;
+            const webhookSecret = params.webhookSecret;
+            if (!apiKeyPrefix) {
+                this.sendError(res, 400, 'Missing apiKey parameter');
+                return;
+            }
+            if (!webhookUrl) {
+                this.sendError(res, 400, 'Missing webhookUrl parameter');
+                return;
+            }
+            // SSRF check
+            const ssrfError = (0, webhook_1.checkSsrf)(webhookUrl);
+            if (ssrfError) {
+                this.sendError(res, 400, `Webhook URL blocked: ${ssrfError}`);
+                return;
+            }
+            // Find key
+            const allKeys = this.gate.store.getAllRecords();
+            const keyRecord = allKeys.find((k) => k.key.startsWith(apiKeyPrefix));
+            if (!keyRecord) {
+                this.sendError(res, 404, 'API key not found');
+                return;
+            }
+            keyRecord.webhookUrl = webhookUrl;
+            if (webhookSecret !== undefined) {
+                keyRecord.webhookSecret = webhookSecret;
+            }
+            this.gate.store.save();
+            // Reset cached emitter so next event creates fresh one
+            this.gate.removeKeyWebhook(keyRecord.key);
+            this.audit.log('key.webhook_updated', 'admin', `Per-key webhook set for ${keyRecord.name}`, {
+                keyPrefix: keyRecord.key.slice(0, 7),
+                webhookUrl: webhookUrl.replace(/\/\/([^:]+):([^@]+)@/, '//$1:***@'), // mask credentials
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                ok: true,
+                keyName: keyRecord.name,
+                webhookUrl,
+                webhookSecret: webhookSecret ? '***' : null,
+            }));
+            return;
+        }
+        if (req.method === 'DELETE') {
+            // Remove per-key webhook URL
+            const url = new URL(req.url || '/', 'http://localhost');
+            const apiKeyPrefix = url.searchParams.get('apiKey');
+            if (!apiKeyPrefix) {
+                this.sendError(res, 400, 'Missing apiKey query parameter');
+                return;
+            }
+            const allKeys2 = this.gate.store.getAllRecords();
+            const keyRecord = allKeys2.find((k) => k.key.startsWith(apiKeyPrefix));
+            if (!keyRecord) {
+                this.sendError(res, 404, 'API key not found');
+                return;
+            }
+            delete keyRecord.webhookUrl;
+            delete keyRecord.webhookSecret;
+            this.gate.store.save();
+            // Destroy cached emitter
+            this.gate.removeKeyWebhook(keyRecord.key);
+            this.audit.log('key.webhook_updated', 'admin', `Per-key webhook removed for ${keyRecord.name}`, {
+                keyPrefix: keyRecord.key.slice(0, 7),
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, keyName: keyRecord.name, webhookUrl: null }));
+            return;
+        }
+        if (req.method === 'GET') {
+            // Get per-key webhook status
+            const url = new URL(req.url || '/', 'http://localhost');
+            const apiKeyPrefix = url.searchParams.get('apiKey');
+            if (!apiKeyPrefix) {
+                this.sendError(res, 400, 'Missing apiKey query parameter');
+                return;
+            }
+            const allKeys3 = this.gate.store.getAllRecords();
+            const keyRecord = allKeys3.find((k) => k.key.startsWith(apiKeyPrefix));
+            if (!keyRecord) {
+                this.sendError(res, 404, 'API key not found');
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                keyName: keyRecord.name,
+                webhookUrl: keyRecord.webhookUrl || null,
+                webhookSecret: keyRecord.webhookSecret ? '***' : null,
+                configured: !!keyRecord.webhookUrl,
+            }));
+            return;
+        }
+        this.sendError(res, 405, 'Method not allowed. Use GET, POST, or DELETE.');
+    }
     handleKeyExport(req, res) {
         if (req.method !== 'GET') {
             this.sendError(res, 405, 'Method not allowed');
@@ -7192,6 +7475,44 @@ class PayGateServer {
             generatedAt: new Date().toISOString(),
         });
     }
+    // ─── /admin/compliance/export — Framework-specific audit export ──────────
+    handleComplianceExport(req, res) {
+        if (!this.checkAdmin(req, res))
+            return;
+        const url = new URL(req.url || '/', `http://localhost`);
+        const framework = (url.searchParams.get('framework') || 'soc2');
+        const format = url.searchParams.get('format') || 'json';
+        const since = url.searchParams.get('since') || undefined;
+        const until = url.searchParams.get('until') || undefined;
+        const validFrameworks = ['soc2', 'gdpr', 'hipaa'];
+        if (!validFrameworks.includes(framework)) {
+            this.sendError(res, 400, `Invalid framework. Must be one of: ${validFrameworks.join(', ')}`);
+            return;
+        }
+        const report = (0, compliance_1.generateComplianceReport)(this.audit, framework, {
+            since,
+            until,
+            serverVersion: PKG_VERSION,
+        });
+        this.audit.log('config.export', 'admin', `Compliance report exported: ${framework} (${format})`, {
+            framework, format, events: report.meta.totalEvents,
+        });
+        if (format === 'csv') {
+            const csv = (0, compliance_1.complianceReportToCsv)(report);
+            res.writeHead(200, {
+                'Content-Type': 'text/csv',
+                'Content-Disposition': `attachment; filename="compliance-${framework}-${new Date().toISOString().slice(0, 10)}.csv"`,
+            });
+            res.end(csv);
+            return;
+        }
+        // JSON (default) with download Content-Disposition
+        res.writeHead(200, {
+            'Content-Type': 'application/json',
+            'Content-Disposition': `attachment; filename="compliance-${framework}-${new Date().toISOString().slice(0, 10)}.json"`,
+        });
+        res.end(JSON.stringify(report, null, 2));
+    }
     // ─── /admin/sla — SLA Monitoring ─────────────────────────────────────────
     handleSlaMonitoring(req, res) {
         if (!this.checkAdmin(req, res))
@@ -12026,6 +12347,14 @@ class PayGateServer {
         else if (this.gate.webhook) {
             this.gate.webhook.emitAdmin(type, actor, metadata);
         }
+        // Per-key webhook: also emit to key-specific webhook if the event references a key
+        const apiKey = (metadata.apiKey || metadata.key);
+        if (apiKey) {
+            const keyWebhook = this.gate.getKeyWebhook(apiKey);
+            if (keyWebhook) {
+                keyWebhook.emitAdmin(type, actor, metadata);
+            }
+        }
     }
     syncKeyMutation(apiKey) {
         if (!this.redisSync)
@@ -12804,6 +13133,238 @@ class PayGateServer {
             tools,
         });
     }
+    // ─── /admin/guardrails — Guardrail rule management ─────────────────────────
+    async handleGuardrails(req, res) {
+        if (req.method === 'GET') {
+            if (!this.checkAdmin(req, res, 'viewer'))
+                return;
+            this.sendJson(res, 200, {
+                enabled: this.guardrails.isEnabled,
+                rules: this.guardrails.getRules(),
+                stats: this.guardrails.getStats(),
+            });
+            return;
+        }
+        if (req.method === 'POST') {
+            if (!this.checkAdmin(req, res, 'admin'))
+                return;
+            const body = await this.readBody(req);
+            let params;
+            try {
+                params = safeJsonParse(body);
+            }
+            catch {
+                this.sendError(res, 400, 'Invalid JSON');
+                return;
+            }
+            // Toggle enabled/disabled
+            if (params.enabled !== undefined) {
+                this.guardrails.setEnabled(!!params.enabled);
+                this.audit.log('guardrail.toggle', 'admin', `Guardrails ${params.enabled ? 'enabled' : 'disabled'}`);
+                this.sendJson(res, 200, { enabled: this.guardrails.isEnabled });
+                return;
+            }
+            // Upsert a rule
+            if (params.rule && typeof params.rule === 'object') {
+                const rule = params.rule;
+                if (!rule.id || !rule.name || !rule.pattern || !rule.action) {
+                    this.sendError(res, 400, 'Rule requires: id, name, pattern, action');
+                    return;
+                }
+                if (!['log', 'warn', 'block', 'redact'].includes(rule.action)) {
+                    this.sendError(res, 400, 'Invalid action. Must be: log, warn, block, redact');
+                    return;
+                }
+                // Validate regex compiles
+                try {
+                    new RegExp(rule.pattern, rule.flags ?? 'gi');
+                }
+                catch {
+                    this.sendError(res, 400, 'Invalid regex pattern');
+                    return;
+                }
+                const saved = this.guardrails.upsertRule({
+                    ...rule,
+                    active: rule.active !== false,
+                    scope: rule.scope || 'both',
+                    tools: rule.tools || [],
+                });
+                this.audit.log('guardrail.rule_upsert', 'admin', `Guardrail rule upserted: ${saved.name}`, { ruleId: saved.id, action: saved.action });
+                this.sendJson(res, 200, { rule: saved });
+                return;
+            }
+            // Import rules
+            if (params.rules && Array.isArray(params.rules)) {
+                const mode = params.mode === 'replace' ? 'replace' : 'merge';
+                const count = this.guardrails.importRules(params.rules, mode);
+                this.audit.log('guardrail.rules_import', 'admin', `Imported ${count} guardrail rules (${mode})`);
+                this.sendJson(res, 200, { imported: count, mode, totalRules: this.guardrails.getRules().length });
+                return;
+            }
+            this.sendError(res, 400, 'Provide "enabled" (boolean), "rule" (object), or "rules" (array)');
+            return;
+        }
+        if (req.method === 'DELETE') {
+            if (!this.checkAdmin(req, res, 'admin'))
+                return;
+            const url = new URL(req.url || '', `http://localhost`);
+            const ruleId = url.searchParams.get('id');
+            if (!ruleId) {
+                this.sendError(res, 400, 'Missing ?id= query parameter');
+                return;
+            }
+            const removed = this.guardrails.removeRule(ruleId);
+            if (!removed) {
+                this.sendError(res, 404, `Rule not found: ${ruleId}`);
+                return;
+            }
+            this.audit.log('guardrail.rule_delete', 'admin', `Guardrail rule deleted: ${ruleId}`);
+            this.sendJson(res, 200, { deleted: ruleId });
+            return;
+        }
+        this.sendError(res, 405, 'Method not allowed. Use GET/POST/DELETE.');
+    }
+    // ─── /admin/guardrails/violations — View guardrail violations ──────────────
+    handleGuardrailViolations(req, res) {
+        if (req.method === 'GET') {
+            if (!this.checkAdmin(req, res, 'viewer'))
+                return;
+            const url = new URL(req.url || '', `http://localhost`);
+            const limit = clampInt(parseInt(url.searchParams.get('limit') || '100', 10), 1, 1000);
+            const offset = clampInt(parseInt(url.searchParams.get('offset') || '0', 10), 0, 100_000);
+            const ruleId = url.searchParams.get('ruleId') || undefined;
+            const tool = url.searchParams.get('tool') || undefined;
+            const action = url.searchParams.get('action') || undefined;
+            const since = url.searchParams.get('since') || undefined;
+            const until = url.searchParams.get('until') || undefined;
+            const result = this.guardrails.queryViolations({ ruleId, tool, action, since, until, limit, offset });
+            this.sendJson(res, 200, {
+                violations: result.violations,
+                total: result.total,
+                limit,
+                offset,
+                hasMore: offset + limit < result.total,
+            });
+            return;
+        }
+        if (req.method === 'DELETE') {
+            if (!this.checkAdmin(req, res, 'admin'))
+                return;
+            const cleared = this.guardrails.clearViolations();
+            this.sendJson(res, 200, { cleared });
+            return;
+        }
+        this.sendError(res, 405, 'Method not allowed. Use GET/DELETE.');
+    }
+    // ─── /keys/geo — Per-key geo-restriction management ─────────────────────────
+    async handleKeyGeo(req, res) {
+        if (!this.checkAdmin(req, res, 'admin'))
+            return;
+        if (req.method === 'GET') {
+            const url = new URL(req.url || '', `http://localhost`);
+            const apiKeyPrefix = url.searchParams.get('key');
+            if (!apiKeyPrefix) {
+                this.sendError(res, 400, 'Missing ?key= query parameter (key prefix)');
+                return;
+            }
+            const record = this.gate.store.getAllRecords().find((k) => k.key.startsWith(apiKeyPrefix));
+            if (!record) {
+                this.sendError(res, 404, 'Key not found');
+                return;
+            }
+            this.sendJson(res, 200, {
+                keyPrefix: record.key.slice(0, 10) + '...',
+                allowedCountries: record.allowedCountries || [],
+                deniedCountries: record.deniedCountries || [],
+            });
+            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;
+            }
+            const apiKeyPrefix = params.key;
+            if (!apiKeyPrefix) {
+                this.sendError(res, 400, 'Missing "key" parameter (key prefix)');
+                return;
+            }
+            const record = this.gate.store.getAllRecords().find((k) => k.key.startsWith(apiKeyPrefix));
+            if (!record) {
+                this.sendError(res, 404, 'Key not found');
+                return;
+            }
+            // Validate country codes (ISO 3166-1 alpha-2)
+            const COUNTRY_CODE_RE = /^[A-Z]{2}$/;
+            if (params.allowedCountries !== undefined) {
+                if (!Array.isArray(params.allowedCountries)) {
+                    this.sendError(res, 400, '"allowedCountries" must be an array of ISO 3166-1 alpha-2 codes');
+                    return;
+                }
+                const codes = params.allowedCountries.map(c => String(c).toUpperCase());
+                if (codes.some(c => !COUNTRY_CODE_RE.test(c))) {
+                    this.sendError(res, 400, 'Invalid country code. Use ISO 3166-1 alpha-2 (e.g., "US", "GB", "DE")');
+                    return;
+                }
+                record.allowedCountries = codes.length > 0 ? codes : undefined;
+            }
+            if (params.deniedCountries !== undefined) {
+                if (!Array.isArray(params.deniedCountries)) {
+                    this.sendError(res, 400, '"deniedCountries" must be an array of ISO 3166-1 alpha-2 codes');
+                    return;
+                }
+                const codes = params.deniedCountries.map(c => String(c).toUpperCase());
+                if (codes.some(c => !COUNTRY_CODE_RE.test(c))) {
+                    this.sendError(res, 400, 'Invalid country code. Use ISO 3166-1 alpha-2 (e.g., "US", "GB", "DE")');
+                    return;
+                }
+                record.deniedCountries = codes.length > 0 ? codes : undefined;
+            }
+            this.gate.store.save();
+            if (this.redisSync)
+                this.redisSync.saveKey(record).catch(() => { });
+            this.audit.log('key.geo_set', 'admin', `Geo restrictions set for ${record.key.slice(0, 10)}...`, {
+                keyMasked: (0, audit_1.maskKeyForAudit)(record.key),
+                allowedCountries: record.allowedCountries || [],
+                deniedCountries: record.deniedCountries || [],
+            });
+            this.sendJson(res, 200, {
+                keyPrefix: record.key.slice(0, 10) + '...',
+                allowedCountries: record.allowedCountries || [],
+                deniedCountries: record.deniedCountries || [],
+            });
+            return;
+        }
+        if (req.method === 'DELETE') {
+            const url = new URL(req.url || '', `http://localhost`);
+            const apiKeyPrefix = url.searchParams.get('key');
+            if (!apiKeyPrefix) {
+                this.sendError(res, 400, 'Missing ?key= query parameter (key prefix)');
+                return;
+            }
+            const record = this.gate.store.getAllRecords().find((k) => k.key.startsWith(apiKeyPrefix));
+            if (!record) {
+                this.sendError(res, 404, 'Key not found');
+                return;
+            }
+            record.allowedCountries = undefined;
+            record.deniedCountries = undefined;
+            this.gate.store.save();
+            if (this.redisSync)
+                this.redisSync.saveKey(record).catch(() => { });
+            this.audit.log('key.geo_cleared', 'admin', `Geo restrictions cleared for ${record.key.slice(0, 10)}...`, {
+                keyMasked: (0, audit_1.maskKeyForAudit)(record.key),
+            });
+            this.sendJson(res, 200, { keyPrefix: record.key.slice(0, 10) + '...', allowedCountries: [], deniedCountries: [] });
+            return;
+        }
+        this.sendError(res, 405, 'Method not allowed. Use GET/POST/DELETE.');
+    }
     /** Calculate percentile from an array of numbers. */
     percentile(values, p) {
         if (values.length === 0)