paygate-mcp 3.1.0 → 3.3.0

package/dist/server.js

@@ -46,6 +46,7 @@ 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");
 /** Max request body size: 1MB */
 const MAX_BODY_SIZE = 1_048_576;
 class PayGateServer {
@@ -56,7 +57,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;
@@ -90,7 +94,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 +144,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
@@ -161,10 +172,24 @@ class PayGateServer {
         this.gate.teamRecorder = (apiKey, credits) => {
             this.teams.recordUsage(apiKey, credits);
         };
-        // 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');
+        // Wire auto-topup hook: audit log + webhook + Redis sync
+        this.gate.onAutoTopup = (apiKey, amount, newBalance) => {
+            const keyMasked = (0, audit_1.maskKeyForAudit)(apiKey);
+            this.audit.log('key.auto_topped_up', 'system', `Auto-topup: added ${amount} credits`, {
+                keyMasked, creditsAdded: amount, newBalance,
+            });
+            this.gate.webhook?.emitAdmin('key.auto_topped_up', 'system', {
+                keyMasked, creditsAdded: amount, newBalance,
+            });
+            // Sync to Redis (if configured)
+            if (this.redisSync) {
+                this.redisSync.atomicTopup(apiKey, amount).catch(() => { });
+            }
+        };
+        // 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) {
@@ -208,7 +233,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);
         });
@@ -259,6 +284,8 @@ class PayGateServer {
                 return this.handleSetIpAllowlist(req, res);
             case '/keys/search':
                 return this.handleSearchKeysByTag(req, res);
+            case '/keys/auto-topup':
+                return this.handleSetAutoTopup(req, res);
             case '/topup':
                 return this.handleTopUp(req, res);
             case '/balance':
@@ -330,6 +357,15 @@ 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);
             // ─── OAuth 2.1 endpoints ─────────────────────────────────────────
             case '/.well-known/oauth-authorization-server':
                 return this.handleOAuthMetadata(req, res);
@@ -701,6 +737,7 @@ class PayGateServer {
                 setTags: 'POST /keys/tags — Set key tags/metadata (requires X-Admin-Key)',
                 setIpAllowlist: 'POST /keys/ip — Set IP allowlist (requires X-Admin-Key)',
                 searchKeys: 'POST /keys/search — Search keys by tags (requires X-Admin-Key)',
+                autoTopup: 'POST /keys/auto-topup — Configure auto-topup for a key (requires X-Admin-Key)',
                 pricing: 'GET /pricing — Tool pricing breakdown (public)',
                 mcpPayment: 'GET /.well-known/mcp-payment — Payment metadata (SEP-2007)',
                 audit: 'GET /audit — Query audit log (requires X-Admin-Key)',
@@ -720,6 +757,9 @@ 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)',
                 ...(this.oauth ? {
                     oauthMetadata: 'GET /.well-known/oauth-authorization-server — OAuth 2.1 server metadata',
                     oauthRegister: 'POST /oauth/register — Register OAuth client',
@@ -781,7 +821,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;
@@ -874,7 +914,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;
@@ -929,7 +969,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;
@@ -975,7 +1015,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;
@@ -1027,7 +1067,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;
@@ -1071,7 +1111,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;
@@ -1121,7 +1161,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;
@@ -1177,7 +1217,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;
@@ -1224,7 +1264,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;
@@ -1292,6 +1332,79 @@ class PayGateServer {
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ keys: results, count: results.length }));
     }
+    // ─── /keys/auto-topup — Configure auto-topup ────────────────────────────────
+    async handleSetAutoTopup(req, res) {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed' }));
+            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;
+        }
+        if (!params.key) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing key' }));
+            return;
+        }
+        const record = this.gate.store.getKey(params.key);
+        if (!record) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Key not found or inactive' }));
+            return;
+        }
+        // Disable auto-topup
+        if (params.disable) {
+            record.autoTopup = undefined;
+            this.gate.store.save();
+            this.syncKeyMutation(params.key);
+            this.audit.log('key.auto_topup_configured', 'admin', 'Auto-topup disabled', {
+                keyMasked: (0, audit_1.maskKeyForAudit)(params.key),
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ autoTopup: null, message: 'Auto-topup disabled' }));
+            return;
+        }
+        // Validate params
+        const threshold = Math.max(0, Math.floor(Number(params.threshold) || 0));
+        const amount = Math.max(0, Math.floor(Number(params.amount) || 0));
+        const maxDaily = Math.max(0, Math.floor(Number(params.maxDaily) || 0));
+        if (threshold <= 0) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'threshold must be a positive integer' }));
+            return;
+        }
+        if (amount <= 0) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'amount must be a positive integer' }));
+            return;
+        }
+        record.autoTopup = { threshold, amount, maxDaily };
+        this.gate.store.save();
+        this.syncKeyMutation(params.key);
+        this.audit.log('key.auto_topup_configured', 'admin', `Auto-topup configured: threshold=${threshold}, amount=${amount}, maxDaily=${maxDaily}`, {
+            keyMasked: (0, audit_1.maskKeyForAudit)(params.key),
+            threshold, amount, maxDaily,
+        });
+        this.gate.webhook?.emitAdmin('key.auto_topup_configured', 'admin', {
+            keyMasked: (0, audit_1.maskKeyForAudit)(params.key), threshold, amount, maxDaily,
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            autoTopup: record.autoTopup,
+            message: `Auto-topup enabled: add ${amount} credits when balance drops below ${threshold}` +
+                (maxDaily > 0 ? ` (max ${maxDaily}/day)` : ' (unlimited daily)'),
+        }));
+    }
     // ─── /balance — Client self-service ────────────────────────────────────────
     handleBalance(req, res) {
         if (req.method !== 'GET') {
@@ -1347,7 +1460,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;
@@ -1792,7 +1905,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;
@@ -1852,7 +1965,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' });
@@ -1958,9 +2071,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,
@@ -1969,6 +2083,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 ────────────────────────────────────────────
@@ -1988,7 +2114,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' });
@@ -2027,7 +2153,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' });
@@ -2067,7 +2193,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' });
@@ -2101,7 +2227,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' });
@@ -2150,7 +2276,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' });
@@ -2230,7 +2356,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;
@@ -2285,7 +2411,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;
@@ -2357,6 +2483,124 @@ class PayGateServer {
             })),
         }));
     }
+    // ─── /admin/keys — 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).