paygate-mcp 3.3.0 → 3.5.0

package/dist/server.js

@@ -47,6 +47,8 @@ const redis_client_1 = require("./redis-client");
 const redis_sync_1 = require("./redis-sync");
 const tokens_1 = require("./tokens");
 const admin_keys_1 = require("./admin-keys");
+const plugin_1 = require("./plugin");
+const groups_1 = require("./groups");
 /** Max request body size: 1MB */
 const MAX_BODY_SIZE = 1_048_576;
 class PayGateServer {
@@ -82,6 +84,9 @@ class PayGateServer {
     redisSync = null;
     /** Scoped token manager for short-lived delegated tokens */
     tokens;
+    /** Plugin manager for extensible middleware hooks */
+    plugins;
+    groups;
     /** Server start time (ms since epoch) */
     startedAt = Date.now();
     /** Whether the server is draining (shutting down gracefully) */
@@ -186,6 +191,17 @@ class PayGateServer {
                 this.redisSync.atomicTopup(apiKey, amount).catch(() => { });
             }
         };
+        // Plugin manager for extensible middleware hooks
+        this.plugins = new plugin_1.PluginManager();
+        this.gate.pluginManager = this.plugins;
+        this.groups = new groups_1.KeyGroupManager();
+        this.gate.groupManager = this.groups;
+        this.metrics.registerGauge('paygate_plugins_total', 'Number of registered plugins', () => {
+            return this.plugins.count;
+        });
+        this.metrics.registerGauge('paygate_groups_total', 'Number of active key groups', () => {
+            return this.groups.count;
+        });
         // Scoped token manager (uses bootstrap admin key as signing secret, padded to min length)
         const tokenSecret = this.bootstrapAdminKey.length >= 8
             ? this.bootstrapAdminKey
@@ -212,6 +228,22 @@ class PayGateServer {
             };
         }
     }
+    /**
+     * Register a plugin for extensible middleware hooks.
+     * Plugins run in registration order.
+     *
+     * @example
+     * ```ts
+     * server.use({
+     *   name: 'custom-pricing',
+     *   transformPrice: (tool, base) => tool.startsWith('premium_') ? base * 5 : null,
+     * });
+     * ```
+     */
+    use(plugin) {
+        this.plugins.register(plugin);
+        return this;
+    }
     async start() {
         // Initialize Redis sync before starting (loads state from Redis + starts pub/sub)
         if (this.redisSync) {
@@ -220,6 +252,10 @@ class PayGateServer {
             console.log('[paygate] Redis distributed state enabled');
         }
         await this.handler.start();
+        // Plugin lifecycle: onStart
+        if (this.plugins.count > 0) {
+            await this.plugins.executeStart();
+        }
         return new Promise((resolve, reject) => {
             this.server = (0, http_1.createServer)(async (req, res) => {
                 try {
@@ -249,6 +285,12 @@ class PayGateServer {
             res.end();
             return;
         }
+        // Plugin: onRequest — let plugins handle custom endpoints before routing
+        if (this.plugins.count > 0) {
+            const handled = await this.plugins.executeOnRequest(req, res);
+            if (handled)
+                return;
+        }
         const url = req.url?.split('?')[0] || '/';
         switch (url) {
             case '/mcp':
@@ -366,6 +408,23 @@ class PayGateServer {
                 break;
             case '/admin/keys/revoke':
                 return this.handleRevokeAdminKey(req, res);
+            // ─── Plugin endpoints ──────────────────────────────────────────────
+            case '/plugins':
+                return this.handleListPlugins(req, res);
+            case '/groups':
+                if (req.method === 'GET')
+                    return this.handleListGroups(req, res);
+                if (req.method === 'POST')
+                    return this.handleCreateGroup(req, res);
+                break;
+            case '/groups/update':
+                return this.handleUpdateGroup(req, res);
+            case '/groups/delete':
+                return this.handleDeleteGroup(req, res);
+            case '/groups/assign':
+                return this.handleAssignKeyToGroup(req, res);
+            case '/groups/remove':
+                return this.handleRemoveKeyFromGroup(req, res);
             // ─── OAuth 2.1 endpoints ─────────────────────────────────────────
             case '/.well-known/oauth-authorization-server':
                 return this.handleOAuthMetadata(req, res);
@@ -488,7 +547,22 @@ class PayGateServer {
             }
             return;
         }
-        const response = await this.handler.handleRequest(request, apiKey, clientIp, scopedTokenTools);
+        // Plugin: beforeToolCall — let plugins modify the request before forwarding
+        let pluginRequest = request;
+        if (this.plugins.count > 0 && request.method === 'tools/call') {
+            const toolName = request.params?.name || '';
+            const toolArgs = request.params?.arguments;
+            const pluginCtx = { apiKey, toolName, toolArgs, request };
+            pluginRequest = await this.plugins.executeBeforeToolCall(pluginCtx);
+        }
+        let response = await this.handler.handleRequest(pluginRequest, apiKey, clientIp, scopedTokenTools);
+        // Plugin: afterToolCall — let plugins modify the response
+        if (this.plugins.count > 0 && request.method === 'tools/call') {
+            const toolName = request.params?.name || '';
+            const toolArgs = request.params?.arguments;
+            const pluginCtx = { apiKey, toolName, toolArgs, request };
+            response = await this.plugins.executeAfterToolCall(pluginCtx, response);
+        }
         // Inject pricing metadata into tools/list responses
         if (request.method === 'tools/list' && response.result) {
             const result = response.result;
@@ -760,6 +834,13 @@ class PayGateServer {
                 adminKeys: 'GET /admin/keys — List admin keys (requires X-Admin-Key, super_admin)',
                 createAdminKey: 'POST /admin/keys — Create admin key with role (requires X-Admin-Key, super_admin)',
                 revokeAdminKey: 'POST /admin/keys/revoke — Revoke an admin key (requires X-Admin-Key, super_admin)',
+                plugins: 'GET /plugins — List registered plugins (requires X-Admin-Key)',
+                listGroups: 'GET /groups — List key groups (requires X-Admin-Key)',
+                createGroup: 'POST /groups — Create a key group (requires X-Admin-Key)',
+                updateGroup: 'POST /groups/update — Update group settings (requires X-Admin-Key)',
+                deleteGroup: 'POST /groups/delete — Delete a key group (requires X-Admin-Key)',
+                assignKeyToGroup: 'POST /groups/assign — Assign a key to a group (requires X-Admin-Key)',
+                removeKeyFromGroup: 'POST /groups/remove — Remove a key from a group (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',
@@ -2484,6 +2565,241 @@ class PayGateServer {
         }));
     }
     // ─── /admin/keys — Admin key management ────────────────────────────────────
+    // ─── GET /plugins — List registered plugins ─────────────────────────────
+    handleListPlugins(req, res) {
+        if (req.method !== 'GET') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed. Use GET.' }));
+            return;
+        }
+        if (!this.checkAdmin(req, res))
+            return;
+        const plugins = this.plugins.list();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ count: plugins.length, plugins }));
+    }
+    // ─── Key Group Endpoints ─────────────────────────────────────────────────
+    handleListGroups(req, res) {
+        if (!this.checkAdmin(req, res))
+            return;
+        const groups = this.groups.listGroups();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ count: groups.length, groups }));
+    }
+    async handleCreateGroup(req, res) {
+        if (!this.checkAdmin(req, res, 'admin'))
+            return;
+        const body = await this.readBody(req);
+        let params;
+        try {
+            params = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        try {
+            const group = this.groups.createGroup({
+                name: String(params.name || ''),
+                description: params.description,
+                allowedTools: params.allowedTools,
+                deniedTools: params.deniedTools,
+                rateLimitPerMin: params.rateLimitPerMin,
+                toolPricing: params.toolPricing,
+                quota: params.quota ? {
+                    dailyCallLimit: Math.max(0, Math.floor(Number(params.quota.dailyCallLimit) || 0)),
+                    monthlyCallLimit: Math.max(0, Math.floor(Number(params.quota.monthlyCallLimit) || 0)),
+                    dailyCreditLimit: Math.max(0, Math.floor(Number(params.quota.dailyCreditLimit) || 0)),
+                    monthlyCreditLimit: Math.max(0, Math.floor(Number(params.quota.monthlyCreditLimit) || 0)),
+                } : undefined,
+                ipAllowlist: params.ipAllowlist,
+                defaultCredits: params.defaultCredits,
+                maxSpendingLimit: params.maxSpendingLimit,
+                tags: params.tags,
+            });
+            this.audit.log('group.created', 'admin', `Group created: ${group.name}`, { groupId: group.id, name: group.name });
+            res.writeHead(201, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(group));
+        }
+        catch (err) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: err.message }));
+        }
+    }
+    async handleUpdateGroup(req, res) {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed. Use POST.' }));
+            return;
+        }
+        if (!this.checkAdmin(req, res, 'admin'))
+            return;
+        const body = await this.readBody(req);
+        let params;
+        try {
+            params = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        const groupId = String(params.id || '');
+        if (!groupId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing id field' }));
+            return;
+        }
+        try {
+            const group = this.groups.updateGroup(groupId, {
+                name: params.name,
+                description: params.description,
+                allowedTools: params.allowedTools,
+                deniedTools: params.deniedTools,
+                rateLimitPerMin: params.rateLimitPerMin,
+                toolPricing: params.toolPricing,
+                quota: params.quota === null ? null : params.quota ? {
+                    dailyCallLimit: Math.max(0, Math.floor(Number(params.quota.dailyCallLimit) || 0)),
+                    monthlyCallLimit: Math.max(0, Math.floor(Number(params.quota.monthlyCallLimit) || 0)),
+                    dailyCreditLimit: Math.max(0, Math.floor(Number(params.quota.dailyCreditLimit) || 0)),
+                    monthlyCreditLimit: Math.max(0, Math.floor(Number(params.quota.monthlyCreditLimit) || 0)),
+                } : undefined,
+                ipAllowlist: params.ipAllowlist,
+                defaultCredits: params.defaultCredits,
+                maxSpendingLimit: params.maxSpendingLimit,
+                tags: params.tags,
+            });
+            this.audit.log('group.updated', 'admin', `Group updated: ${group.name}`, { groupId: group.id });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(group));
+        }
+        catch (err) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: err.message }));
+        }
+    }
+    async handleDeleteGroup(req, res) {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed. Use POST.' }));
+            return;
+        }
+        if (!this.checkAdmin(req, res, 'admin'))
+            return;
+        const body = await this.readBody(req);
+        let params;
+        try {
+            params = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        const groupId = String(params.id || '');
+        if (!groupId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing id field' }));
+            return;
+        }
+        const deleted = this.groups.deleteGroup(groupId);
+        if (!deleted) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Group not found' }));
+            return;
+        }
+        this.audit.log('group.deleted', 'admin', `Group deleted: ${groupId}`, { groupId });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, message: `Group ${groupId} deleted` }));
+    }
+    async handleAssignKeyToGroup(req, res) {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed. Use POST.' }));
+            return;
+        }
+        if (!this.checkAdmin(req, res, 'admin'))
+            return;
+        const body = await this.readBody(req);
+        let params;
+        try {
+            params = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        const apiKey = String(params.key || '');
+        const groupId = String(params.groupId || '');
+        if (!apiKey || !groupId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing key or groupId field' }));
+            return;
+        }
+        // Verify key exists
+        const keyRecord = this.gate.store.getKey(apiKey);
+        if (!keyRecord) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'API key not found' }));
+            return;
+        }
+        try {
+            this.groups.assignKey(apiKey, groupId);
+            // Update key record's group field
+            keyRecord.group = groupId;
+            this.audit.log('group.key_assigned', 'admin', `Key assigned to group ${groupId}`, {
+                keyMasked: (0, audit_1.maskKeyForAudit)(apiKey), groupId,
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, message: `Key assigned to group ${groupId}` }));
+        }
+        catch (err) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: err.message }));
+        }
+    }
+    async handleRemoveKeyFromGroup(req, res) {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed. Use POST.' }));
+            return;
+        }
+        if (!this.checkAdmin(req, res, 'admin'))
+            return;
+        const body = await this.readBody(req);
+        let params;
+        try {
+            params = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        const apiKey = String(params.key || '');
+        if (!apiKey) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing key field' }));
+            return;
+        }
+        const removed = this.groups.removeKey(apiKey);
+        if (!removed) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Key not in any group' }));
+            return;
+        }
+        // Clear group field on key record
+        const keyRecord = this.gate.store.getKey(apiKey);
+        if (keyRecord) {
+            delete keyRecord.group;
+        }
+        this.audit.log('group.key_removed', 'admin', `Key removed from group`, { keyMasked: (0, audit_1.maskKeyForAudit)(apiKey) });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, message: 'Key removed from group' }));
+    }
+    // ─── Admin Key Management ────────────────────────────────────────────────
     handleListAdminKeys(req, res) {
         if (req.method !== 'GET') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
@@ -2634,6 +2950,10 @@ class PayGateServer {
         });
     }
     async stop() {
+        // Plugin lifecycle: onStop (reverse order)
+        if (this.plugins.count > 0) {
+            await this.plugins.executeStop();
+        }
         await this.handler.stop();
         this.gate.destroy();
         this.oauth?.destroy();
@@ -2684,6 +3004,10 @@ class PayGateServer {
             check();
         });
         console.log('[paygate] Drained — tearing down resources');
+        // Plugin lifecycle: onStop (reverse order)
+        if (this.plugins.count > 0) {
+            await this.plugins.executeStop();
+        }
         // Tear down resources (but skip server.close, already closed above)
         await this.handler.stop();
         this.gate.destroy();