paygate-mcp 3.3.0 → 3.4.0

package/dist/plugin.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Plugin System — Extensible middleware hooks for custom billing, auth,
+ * pricing, logging, and request handling logic.
+ *
+ * Plugins register named hook functions that run at key points in the
+ * request lifecycle:
+ *
+ *   Gate hooks (synchronous — hot path):
+ *     - beforeGate:     Short-circuit gate evaluation (deny/allow early)
+ *     - afterGate:      Modify gate decision after evaluation
+ *     - onDeny:         Notification when a tool call is denied
+ *     - transformPrice: Override tool pricing dynamically
+ *
+ *   Tool hooks (async — wraps proxy forward):
+ *     - beforeToolCall: Modify request before forwarding to MCP server
+ *     - afterToolCall:  Modify response after receiving from MCP server
+ *
+ *   HTTP hooks (async):
+ *     - onRequest:      Handle custom HTTP endpoints before normal routing
+ *
+ *   Lifecycle hooks (async):
+ *     - onStart:        Called when the server starts
+ *     - onStop:         Called when the server stops
+ *
+ * Plugins run in registration order. Gate hooks are sync to avoid adding
+ * latency to the critical billing path. Tool/HTTP/lifecycle hooks may be async.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginManager = void 0;
+// ─── Plugin Manager ───────────────────────────────────────────────────────
+class PluginManager {
+    plugins = [];
+    /** Register a plugin. Plugins run in registration order. */
+    register(plugin) {
+        if (!plugin.name) {
+            throw new Error('Plugin must have a name');
+        }
+        if (this.plugins.some(p => p.name === plugin.name)) {
+            throw new Error(`Plugin "${plugin.name}" is already registered`);
+        }
+        this.plugins.push(plugin);
+    }
+    /** Unregister a plugin by name. Returns true if found and removed. */
+    unregister(name) {
+        const idx = this.plugins.findIndex(p => p.name === name);
+        if (idx === -1)
+            return false;
+        this.plugins.splice(idx, 1);
+        return true;
+    }
+    /** List all registered plugins with their hooks. */
+    list() {
+        return this.plugins.map(p => ({
+            name: p.name,
+            version: p.version,
+            hooks: this.getPluginHooks(p),
+        }));
+    }
+    /** Number of registered plugins. */
+    get count() {
+        return this.plugins.length;
+    }
+    // ─── Gate Hook Execution (synchronous) ────────────────────────────
+    /**
+     * Execute beforeGate hooks in order.
+     * First non-null result short-circuits the gate.
+     */
+    executeBeforeGate(context) {
+        for (const plugin of this.plugins) {
+            if (plugin.beforeGate) {
+                try {
+                    const result = plugin.beforeGate(context);
+                    if (result !== null && result !== undefined)
+                        return result;
+                }
+                catch {
+                    // Plugin errors don't break the gate
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Execute afterGate hooks in order.
+     * Each plugin can modify the decision; changes cascade through.
+     */
+    executeAfterGate(context, decision) {
+        let current = decision;
+        for (const plugin of this.plugins) {
+            if (plugin.afterGate) {
+                try {
+                    current = plugin.afterGate(context, current);
+                }
+                catch {
+                    // Plugin errors don't break the gate
+                }
+            }
+        }
+        return current;
+    }
+    /**
+     * Execute onDeny hooks (fire-and-forget).
+     */
+    executeOnDeny(context, reason) {
+        for (const plugin of this.plugins) {
+            if (plugin.onDeny) {
+                try {
+                    plugin.onDeny(context, reason);
+                }
+                catch {
+                    // Plugin errors don't break the flow
+                }
+            }
+        }
+    }
+    /**
+     * Execute transformPrice hooks. First non-null result wins.
+     */
+    executeTransformPrice(toolName, basePrice, args) {
+        for (const plugin of this.plugins) {
+            if (plugin.transformPrice) {
+                try {
+                    const result = plugin.transformPrice(toolName, basePrice, args);
+                    if (result !== null && result !== undefined && typeof result === 'number') {
+                        return result;
+                    }
+                }
+                catch {
+                    // Plugin errors → fall through to default
+                }
+            }
+        }
+        return basePrice;
+    }
+    // ─── Tool Hook Execution (async) ──────────────────────────────────
+    /**
+     * Execute beforeToolCall hooks in order.
+     * Each can modify the request; changes cascade.
+     */
+    async executeBeforeToolCall(context) {
+        let req = context.request;
+        for (const plugin of this.plugins) {
+            if (plugin.beforeToolCall) {
+                try {
+                    req = await plugin.beforeToolCall({ ...context, request: req });
+                }
+                catch {
+                    // Plugin errors → skip this hook
+                }
+            }
+        }
+        return req;
+    }
+    /**
+     * Execute afterToolCall hooks in order.
+     * Each can modify the response; changes cascade.
+     */
+    async executeAfterToolCall(context, response) {
+        let res = response;
+        for (const plugin of this.plugins) {
+            if (plugin.afterToolCall) {
+                try {
+                    res = await plugin.afterToolCall(context, res);
+                }
+                catch {
+                    // Plugin errors → skip this hook
+                }
+            }
+        }
+        return res;
+    }
+    // ─── HTTP Hook Execution (async) ──────────────────────────────────
+    /**
+     * Execute onRequest hooks. First handler returning true wins.
+     */
+    async executeOnRequest(req, res) {
+        for (const plugin of this.plugins) {
+            if (plugin.onRequest) {
+                try {
+                    const handled = await plugin.onRequest(req, res);
+                    if (handled)
+                        return true;
+                }
+                catch {
+                    // Plugin errors → continue to next plugin
+                }
+            }
+        }
+        return false;
+    }
+    // ─── Lifecycle Hook Execution (async) ─────────────────────────────
+    /**
+     * Execute onStart hooks for all plugins.
+     */
+    async executeStart() {
+        for (const plugin of this.plugins) {
+            if (plugin.onStart) {
+                await plugin.onStart();
+            }
+        }
+    }
+    /**
+     * Execute onStop hooks for all plugins (in reverse order for clean teardown).
+     */
+    async executeStop() {
+        for (let i = this.plugins.length - 1; i >= 0; i--) {
+            const plugin = this.plugins[i];
+            if (plugin.onStop) {
+                try {
+                    await plugin.onStop();
+                }
+                catch {
+                    // Best-effort teardown
+                }
+            }
+        }
+    }
+    // ─── Private ──────────────────────────────────────────────────────
+    getPluginHooks(plugin) {
+        const hooks = [];
+        if (plugin.onStart)
+            hooks.push('onStart');
+        if (plugin.onStop)
+            hooks.push('onStop');
+        if (plugin.beforeGate)
+            hooks.push('beforeGate');
+        if (plugin.afterGate)
+            hooks.push('afterGate');
+        if (plugin.onDeny)
+            hooks.push('onDeny');
+        if (plugin.transformPrice)
+            hooks.push('transformPrice');
+        if (plugin.beforeToolCall)
+            hooks.push('beforeToolCall');
+        if (plugin.afterToolCall)
+            hooks.push('afterToolCall');
+        if (plugin.onRequest)
+            hooks.push('onRequest');
+        return hooks;
+    }
+}
+exports.PluginManager = PluginManager;
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

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

package/dist/server.d.ts

@@ -28,6 +28,7 @@ import { TeamManager } from './teams';
 import { RedisSync } from './redis-sync';
 import { ScopedTokenManager } from './tokens';
 import { AdminKeyManager } from './admin-keys';
+import { PluginManager, PayGatePlugin } from './plugin';
 /** Union type for both proxy backends */
 type ProxyBackend = McpProxy | HttpMcpProxy;
 export declare class PayGateServer {
@@ -63,6 +64,8 @@ export declare class PayGateServer {
     readonly redisSync: RedisSync | null;
     /** Scoped token manager for short-lived delegated tokens */
     readonly tokens: ScopedTokenManager;
+    /** Plugin manager for extensible middleware hooks */
+    readonly plugins: PluginManager;
     /** Server start time (ms since epoch) */
     private readonly startedAt;
     /** Whether the server is draining (shutting down gracefully) */
@@ -74,6 +77,19 @@ export declare class PayGateServer {
     constructor(config: Partial<PayGateConfig> & {
         serverCommand: string;
     }, adminKey?: string, statePath?: string, remoteUrl?: string, stripeWebhookSecret?: string, servers?: ServerBackendConfig[], redisUrl?: string);
+    /**
+     * 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: PayGatePlugin): this;
     start(): Promise<{
         port: number;
         adminKey: string;
@@ -156,6 +172,7 @@ export declare class PayGateServer {
     private handleCreateToken;
     private handleRevokeToken;
     private handleListRevokedTokens;
+    private handleListPlugins;
     private handleListAdminKeys;
     private handleCreateAdminKey;
     private handleRevokeAdminKey;

package/dist/server.d.ts.map

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

package/dist/server.js

@@ -47,6 +47,7 @@ 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");
 /** Max request body size: 1MB */
 const MAX_BODY_SIZE = 1_048_576;
 class PayGateServer {
@@ -82,6 +83,8 @@ class PayGateServer {
     redisSync = null;
     /** Scoped token manager for short-lived delegated tokens */
     tokens;
+    /** Plugin manager for extensible middleware hooks */
+    plugins;
     /** Server start time (ms since epoch) */
     startedAt = Date.now();
     /** Whether the server is draining (shutting down gracefully) */
@@ -186,6 +189,12 @@ 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.metrics.registerGauge('paygate_plugins_total', 'Number of registered plugins', () => {
+            return this.plugins.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 +221,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 +245,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 +278,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 +401,9 @@ class PayGateServer {
                 break;
             case '/admin/keys/revoke':
                 return this.handleRevokeAdminKey(req, res);
+            // ─── Plugin endpoints ──────────────────────────────────────────────
+            case '/plugins':
+                return this.handleListPlugins(req, res);
             // ─── OAuth 2.1 endpoints ─────────────────────────────────────────
             case '/.well-known/oauth-authorization-server':
                 return this.handleOAuthMetadata(req, res);
@@ -488,7 +526,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 +813,7 @@ 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)',
                 ...(this.oauth ? {
                     oauthMetadata: 'GET /.well-known/oauth-authorization-server — OAuth 2.1 server metadata',
                     oauthRegister: 'POST /oauth/register — Register OAuth client',
@@ -2484,6 +2538,20 @@ 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 }));
+    }
+    // ─── Admin Key Management ────────────────────────────────────────────────
     handleListAdminKeys(req, res) {
         if (req.method !== 'GET') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
@@ -2634,6 +2702,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 +2756,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();