paygate-mcp 3.2.0 → 3.4.0

package/dist/server.d.ts

@@ -27,6 +27,8 @@ import { AlertEngine } from './alerts';
 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 {
@@ -37,7 +39,10 @@ export declare class PayGateServer {
     readonly router: MultiServerRouter | null;
     private server;
     private readonly config;
-    private readonly adminKey;
+    /** Admin key manager (multiple keys with role-based permissions) */
+    readonly adminKeys: AdminKeyManager;
+    /** The bootstrap admin key (from constructor or auto-generated) */
+    private readonly bootstrapAdminKey;
     private stripeHandler;
     /** OAuth 2.1 provider (null if OAuth is not enabled) */
     readonly oauth: OAuthProvider | null;
@@ -59,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) */
@@ -70,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;
@@ -152,6 +172,10 @@ export declare class PayGateServer {
     private handleCreateToken;
     private handleRevokeToken;
     private handleListRevokedTokens;
+    private handleListPlugins;
+    private handleListAdminKeys;
+    private handleCreateAdminKey;
+    private handleRevokeAdminKey;
     /**
      * Sync a key mutation to Redis. Call after any local KeyStore mutation
      * (setAcl, setExpiry, setQuota, setTags, setIpAllowlist, setSpendingLimit).

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

@@ -46,6 +46,8 @@ const teams_1 = require("./teams");
 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 {
@@ -56,7 +58,10 @@ class PayGateServer {
     router;
     server = null;
     config;
-    adminKey;
+    /** Admin key manager (multiple keys with role-based permissions) */
+    adminKeys;
+    /** The bootstrap admin key (from constructor or auto-generated) */
+    bootstrapAdminKey;
     stripeHandler = null;
     /** OAuth 2.1 provider (null if OAuth is not enabled) */
     oauth = null;
@@ -78,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) */
@@ -90,7 +97,11 @@ class PayGateServer {
     }
     constructor(config, adminKey, statePath, remoteUrl, stripeWebhookSecret, servers, redisUrl) {
         this.config = { ...types_1.DEFAULT_CONFIG, ...config };
-        this.adminKey = adminKey || `admin_${require('crypto').randomBytes(16).toString('hex')}`;
+        this.bootstrapAdminKey = adminKey || `admin_${require('crypto').randomBytes(16).toString('hex')}`;
+        // Admin key manager with file persistence (separate from API key state)
+        const adminStatePath = statePath ? statePath.replace(/\.json$/, '-admin.json') : undefined;
+        this.adminKeys = new admin_keys_1.AdminKeyManager(adminStatePath);
+        this.adminKeys.bootstrap(this.bootstrapAdminKey);
         this.gate = new gate_1.Gate(this.config, statePath);
         // Multi-server mode: use Router
         if (servers && servers.length > 0) {
@@ -136,6 +147,9 @@ class PayGateServer {
         this.metrics.registerGauge('paygate_total_credits_available', 'Total credits across all active keys', () => {
             return this.gate.store.listKeys().filter(k => k.active).reduce((sum, k) => sum + k.credits, 0);
         });
+        this.metrics.registerGauge('paygate_admin_keys_total', 'Number of active admin keys', () => {
+            return this.adminKeys.activeCount;
+        });
         // Analytics engine
         this.analytics = new analytics_1.AnalyticsEngine();
         // Alert engine
@@ -175,10 +189,16 @@ class PayGateServer {
                 this.redisSync.atomicTopup(apiKey, amount).catch(() => { });
             }
         };
-        // Scoped token manager (uses admin key as signing secret, padded to min length)
-        const tokenSecret = this.adminKey.length >= 8
-            ? this.adminKey
-            : this.adminKey + require('crypto').randomBytes(8).toString('hex');
+        // 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
+            : this.bootstrapAdminKey + require('crypto').randomBytes(8).toString('hex');
         this.tokens = new tokens_1.ScopedTokenManager(tokenSecret);
         // Redis distributed state (if configured)
         if (redisUrl) {
@@ -201,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) {
@@ -209,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 {
@@ -222,7 +262,7 @@ class PayGateServer {
             this.server.listen(this.config.port, () => {
                 const addr = this.server.address();
                 const actualPort = typeof addr === 'object' && addr ? addr.port : this.config.port;
-                resolve({ port: actualPort, adminKey: this.adminKey });
+                resolve({ port: actualPort, adminKey: this.bootstrapAdminKey });
             });
             this.server.on('error', reject);
         });
@@ -238,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':
@@ -346,6 +392,18 @@ class PayGateServer {
                 return this.handleRevokeToken(req, res);
             case '/tokens/revoked':
                 return this.handleListRevokedTokens(req, res);
+            // ─── Admin key management endpoints ──────────────────────────────
+            case '/admin/keys':
+                if (req.method === 'POST')
+                    return this.handleCreateAdminKey(req, res);
+                if (req.method === 'GET')
+                    return this.handleListAdminKeys(req, res);
+                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);
@@ -468,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;
@@ -737,6 +810,10 @@ class PayGateServer {
                 createToken: 'POST /tokens — Create scoped token (requires X-Admin-Key)',
                 revokeToken: 'POST /tokens/revoke — Revoke a scoped token (requires X-Admin-Key)',
                 listRevokedTokens: 'GET /tokens/revoked — List revoked tokens (requires X-Admin-Key)',
+                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',
@@ -798,7 +875,7 @@ class PayGateServer {
     }
     // ─── /keys — Create ─────────────────────────────────────────────────────────
     async handleCreateKey(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -891,7 +968,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -946,7 +1023,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -992,7 +1069,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1044,7 +1121,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1088,7 +1165,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1138,7 +1215,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1194,7 +1271,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1241,7 +1318,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1316,7 +1393,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1437,7 +1514,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1882,7 +1959,7 @@ class PayGateServer {
         }));
     }
     async handleConfigureAlerts(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -1942,7 +2019,7 @@ class PayGateServer {
         }));
     }
     handleClearDeadLetters(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         if (!this.gate.webhook) {
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -2048,9 +2125,10 @@ class PayGateServer {
         res.end(JSON.stringify(this.audit.stats(), null, 2));
     }
     // ─── Helpers ────────────────────────────────────────────────────────────────
-    checkAdmin(req, res) {
+    checkAdmin(req, res, minRole) {
         const adminKey = req.headers['x-admin-key'];
-        if (adminKey !== this.adminKey) {
+        const record = adminKey ? this.adminKeys.validate(adminKey) : null;
+        if (!record) {
             this.audit.log('admin.auth_failed', 'unknown', `Admin auth failed on ${req.url}`, {
                 url: req.url,
                 method: req.method,
@@ -2059,6 +2137,18 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Invalid admin key' }));
             return false;
         }
+        // Role-based permission check (if a minimum role is specified)
+        if (minRole && admin_keys_1.ROLE_HIERARCHY[record.role] < admin_keys_1.ROLE_HIERARCHY[minRole]) {
+            this.audit.log('admin.auth_failed', adminKey.slice(0, 7) + '...' + adminKey.slice(-4), `Insufficient role for ${req.url} (need ${minRole}, have ${record.role})`, {
+                url: req.url,
+                method: req.method,
+                requiredRole: minRole,
+                currentRole: record.role,
+            });
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Insufficient permissions', requiredRole: minRole, currentRole: record.role }));
+            return false;
+        }
         return true;
     }
     // ─── /teams — Team management ────────────────────────────────────────────
@@ -2078,7 +2168,7 @@ class PayGateServer {
         res.end(JSON.stringify({ teams, count: teams.length }));
     }
     async handleCreateTeam(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         if (req.method !== 'POST') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
@@ -2117,7 +2207,7 @@ class PayGateServer {
         res.end(JSON.stringify({ message: 'Team created', team }));
     }
     async handleUpdateTeam(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         if (req.method !== 'POST') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
@@ -2157,7 +2247,7 @@ class PayGateServer {
         res.end(JSON.stringify({ message: 'Team updated', team: this.teams.getTeam(params.teamId) }));
     }
     async handleDeleteTeam(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         if (req.method !== 'POST') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
@@ -2191,7 +2281,7 @@ class PayGateServer {
         res.end(JSON.stringify({ message: 'Team deleted' }));
     }
     async handleTeamAssignKey(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         if (req.method !== 'POST') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
@@ -2240,7 +2330,7 @@ class PayGateServer {
         res.end(JSON.stringify({ message: 'Key assigned to team' }));
     }
     async handleTeamRemoveKey(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         if (req.method !== 'POST') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
@@ -2320,7 +2410,7 @@ class PayGateServer {
     }
     // ─── /tokens — Create scoped token ──────────────────────────────────────────
     async handleCreateToken(req, res) {
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -2375,7 +2465,7 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Method not allowed' }));
             return;
         }
-        if (!this.checkAdmin(req, res))
+        if (!this.checkAdmin(req, res, 'admin'))
             return;
         const body = await this.readBody(req);
         let params;
@@ -2447,6 +2537,138 @@ 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' });
+            res.end(JSON.stringify({ error: 'Method not allowed. Use GET.' }));
+            return;
+        }
+        if (!this.checkAdmin(req, res, 'super_admin'))
+            return;
+        const keys = this.adminKeys.list().map(k => ({
+            key: k.key.slice(0, 7) + '...' + k.key.slice(-4),
+            name: k.name,
+            role: k.role,
+            createdAt: k.createdAt,
+            createdBy: k.createdBy,
+            active: k.active,
+            lastUsedAt: k.lastUsedAt,
+        }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ count: keys.length, keys }));
+    }
+    async handleCreateAdminKey(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, 'super_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 body' }));
+            return;
+        }
+        if (!params.name || typeof params.name !== 'string') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing required field: name' }));
+            return;
+        }
+        const role = (params.role || 'admin');
+        if (!['super_admin', 'admin', 'viewer'].includes(role)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid role. Must be super_admin, admin, or viewer.' }));
+            return;
+        }
+        // Mask the requesting admin key for audit
+        const callerKey = req.headers['x-admin-key'];
+        const callerMasked = callerKey.slice(0, 7) + '...' + callerKey.slice(-4);
+        const record = this.adminKeys.create(params.name, role, callerMasked);
+        this.audit.log('admin_key.created', callerMasked, `Created admin key "${params.name}" with role ${role}`, {
+            newKeyMasked: record.key.slice(0, 7) + '...' + record.key.slice(-4),
+            role,
+        });
+        this.gate.webhook?.emitAdmin('admin_key.created', callerMasked, {
+            newKeyMasked: record.key.slice(0, 7) + '...' + record.key.slice(-4),
+            name: params.name,
+            role,
+        });
+        res.writeHead(201, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            key: record.key,
+            name: record.name,
+            role: record.role,
+            createdAt: record.createdAt,
+        }));
+    }
+    async handleRevokeAdminKey(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, 'super_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 body' }));
+            return;
+        }
+        if (!params.key || typeof params.key !== 'string') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing required field: key' }));
+            return;
+        }
+        const callerKey = req.headers['x-admin-key'];
+        // Prevent revoking your own key
+        if (params.key === callerKey) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Cannot revoke your own admin key' }));
+            return;
+        }
+        const result = this.adminKeys.revoke(params.key);
+        if (!result.success) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: result.error }));
+            return;
+        }
+        const callerMasked = callerKey.slice(0, 7) + '...' + callerKey.slice(-4);
+        const targetMasked = params.key.slice(0, 7) + '...' + params.key.slice(-4);
+        this.audit.log('admin_key.revoked', callerMasked, `Revoked admin key ${targetMasked}`, {
+            revokedKeyMasked: targetMasked,
+        });
+        this.gate.webhook?.emitAdmin('admin_key.revoked', callerMasked, {
+            revokedKeyMasked: targetMasked,
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ revoked: true }));
+    }
     /**
      * Sync a key mutation to Redis. Call after any local KeyStore mutation
      * (setAcl, setExpiry, setQuota, setTags, setIpAllowlist, setSpendingLimit).
@@ -2480,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();
@@ -2530,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();