paygate-mcp 5.0.0 → 5.2.0

package/dist/key-templates.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * KeyTemplateManager — Named templates for API key creation.
+ *
+ * Templates define reusable presets for key creation (credits, ACL, quotas, etc.).
+ * Instead of passing all options every time, use `template: "free-tier"` in POST /keys.
+ *
+ * Features:
+ *   - CRUD: create, update, list, get, delete templates
+ *   - File persistence (-templates.json alongside state file)
+ *   - Templates define: credits, allowedTools, deniedTools, quota, ipAllowlist,
+ *     spendingLimit, tags, namespace, expiryTtlSeconds, autoTopup
+ *   - Max 100 templates
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyTemplateManager = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+// ─── Manager Class ────────────────────────────────────────────────────────────
+const MAX_TEMPLATES = 100;
+class KeyTemplateManager {
+    templates = new Map();
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath || null;
+        if (this.filePath) {
+            this.loadFromFile();
+        }
+    }
+    /**
+     * Create or update a template.
+     */
+    set(name, data) {
+        // Validate name
+        const sanitized = name.trim().slice(0, 50);
+        if (!/^[a-zA-Z0-9_-]+$/.test(sanitized)) {
+            return { success: false, error: 'Template name must contain only letters, numbers, hyphens, and underscores' };
+        }
+        const existing = this.templates.get(sanitized);
+        const now = new Date().toISOString();
+        const template = {
+            name: sanitized,
+            description: String(data.description || existing?.description || '').slice(0, 500),
+            credits: Math.max(0, Math.floor(Number(data.credits ?? existing?.credits ?? 100))),
+            allowedTools: Array.isArray(data.allowedTools) ? data.allowedTools.filter(t => typeof t === 'string').slice(0, 100) : (existing?.allowedTools || []),
+            deniedTools: Array.isArray(data.deniedTools) ? data.deniedTools.filter(t => typeof t === 'string').slice(0, 100) : (existing?.deniedTools || []),
+            quota: data.quota !== undefined ? data.quota : existing?.quota,
+            ipAllowlist: Array.isArray(data.ipAllowlist) ? data.ipAllowlist.filter(t => typeof t === 'string').slice(0, 100) : (existing?.ipAllowlist || []),
+            spendingLimit: Math.max(0, Number(data.spendingLimit ?? existing?.spendingLimit ?? 0)),
+            tags: typeof data.tags === 'object' && data.tags !== null ? data.tags : (existing?.tags || {}),
+            namespace: String(data.namespace || existing?.namespace || 'default').trim().toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 50) || 'default',
+            expiryTtlSeconds: Math.max(0, Math.floor(Number(data.expiryTtlSeconds ?? existing?.expiryTtlSeconds ?? 0))),
+            autoTopup: data.autoTopup !== undefined ? data.autoTopup : existing?.autoTopup,
+            createdAt: existing?.createdAt || now,
+            updatedAt: now,
+        };
+        // Check limit (only for new templates)
+        if (!existing && this.templates.size >= MAX_TEMPLATES) {
+            return { success: false, error: `Maximum ${MAX_TEMPLATES} templates reached` };
+        }
+        this.templates.set(sanitized, template);
+        this.saveToFile();
+        return { success: true, template };
+    }
+    /**
+     * Get a template by name.
+     */
+    get(name) {
+        return this.templates.get(name) || null;
+    }
+    /**
+     * Delete a template.
+     */
+    delete(name) {
+        const existed = this.templates.delete(name);
+        if (existed)
+            this.saveToFile();
+        return existed;
+    }
+    /**
+     * List all templates.
+     */
+    list() {
+        return Array.from(this.templates.values()).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Get template count.
+     */
+    get count() {
+        return this.templates.size;
+    }
+    // ─── File Persistence ──────────────────────────────────────────────────────
+    saveToFile() {
+        if (!this.filePath)
+            return;
+        const data = Array.from(this.templates.entries());
+        const json = JSON.stringify(data, null, 2);
+        const tmpPath = this.filePath + '.tmp';
+        try {
+            (0, fs_1.mkdirSync)((0, path_1.dirname)(this.filePath), { recursive: true });
+            (0, fs_1.writeFileSync)(tmpPath, json, 'utf-8');
+            (0, fs_1.renameSync)(tmpPath, this.filePath);
+        }
+        catch (err) {
+            console.error(`[paygate] Failed to save templates: ${err.message}`);
+        }
+    }
+    loadFromFile() {
+        if (!this.filePath || !(0, fs_1.existsSync)(this.filePath))
+            return;
+        try {
+            const json = (0, fs_1.readFileSync)(this.filePath, 'utf-8');
+            const data = JSON.parse(json);
+            if (!Array.isArray(data))
+                return;
+            for (const [name, template] of data) {
+                if (name && template && typeof template.name === 'string') {
+                    this.templates.set(name, template);
+                }
+            }
+            console.log(`[paygate] Loaded ${this.templates.size} template(s) from ${this.filePath}`);
+        }
+        catch (err) {
+            console.error(`[paygate] Failed to load templates: ${err.message}`);
+        }
+    }
+}
+exports.KeyTemplateManager = KeyTemplateManager;
+//# sourceMappingURL=key-templates.js.map

package/dist/key-templates.js.map

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

package/dist/server.d.ts

@@ -30,6 +30,8 @@ import { ScopedTokenManager } from './tokens';
 import { AdminKeyManager } from './admin-keys';
 import { PluginManager, PayGatePlugin } from './plugin';
 import { KeyGroupManager } from './groups';
+import { ExpiryScanner } from './expiry-scanner';
+import { KeyTemplateManager } from './key-templates';
 /** Union type for both proxy backends */
 type ProxyBackend = McpProxy | HttpMcpProxy;
 export declare class PayGateServer {
@@ -68,6 +70,10 @@ export declare class PayGateServer {
     /** Plugin manager for extensible middleware hooks */
     readonly plugins: PluginManager;
     readonly groups: KeyGroupManager;
+    /** Background key expiry scanner */
+    readonly expiryScanner: ExpiryScanner;
+    /** Key template manager for reusable key presets */
+    readonly templates: KeyTemplateManager;
     /** Server start time (ms since epoch) */
     private readonly startedAt;
     /** Whether the server is draining (shutting down gracefully) */
@@ -148,6 +154,7 @@ export declare class PayGateServer {
     private handleSetIpAllowlist;
     private handleSearchKeysByTag;
     private handleKeyUsage;
+    private handleKeysExpiring;
     private handleSetAutoTopup;
     private handleBalance;
     private handleLimits;
@@ -210,11 +217,9 @@ export declare class PayGateServer {
     private handleListAdminKeys;
     private handleCreateAdminKey;
     private handleRevokeAdminKey;
-    /**
-     * Sync a key mutation to Redis. Call after any local KeyStore mutation
-     * (setAcl, setExpiry, setQuota, setTags, setIpAllowlist, setSpendingLimit).
-     * Fire-and-forget: errors logged, never thrown.
-     */
+    private handleListTemplates;
+    private handleCreateTemplate;
+    private handleDeleteTemplate;
     /**
      * Route admin webhook events through the WebhookRouter (for filter rules) or direct emitter.
      */

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

@@ -83,6 +83,8 @@ const tokens_1 = require("./tokens");
 const admin_keys_1 = require("./admin-keys");
 const plugin_1 = require("./plugin");
 const groups_1 = require("./groups");
+const expiry_scanner_1 = require("./expiry-scanner");
+const key_templates_1 = require("./key-templates");
 /** Max request body size: 1MB */
 const MAX_BODY_SIZE = 1_048_576;
 class PayGateServer {
@@ -121,6 +123,10 @@ class PayGateServer {
     /** Plugin manager for extensible middleware hooks */
     plugins;
     groups;
+    /** Background key expiry scanner */
+    expiryScanner;
+    /** Key template manager for reusable key presets */
+    templates;
     /** Server start time (ms since epoch) */
     startedAt = Date.now();
     /** Whether the server is draining (shutting down gracefully) */
@@ -239,6 +245,30 @@ class PayGateServer {
         this.metrics.registerGauge('paygate_groups_total', 'Number of active key groups', () => {
             return this.groups.count;
         });
+        // Key expiry scanner — proactive background scanning for expiring keys
+        const scannerConfig = this.config.expiryScanner;
+        this.expiryScanner = new expiry_scanner_1.ExpiryScanner(scannerConfig ? {
+            enabled: scannerConfig.enabled !== false,
+            intervalSeconds: scannerConfig.intervalSeconds || 3600,
+            thresholds: scannerConfig.thresholds || [604800, 86400, 3600],
+        } : undefined);
+        // Wire scanner callbacks: audit + webhook
+        this.expiryScanner.onWarning = (warning) => {
+            const keyMasked = (0, audit_1.maskKeyForAudit)(warning.key);
+            this.audit.log('key.expiry_warning', 'system', `Key "${warning.name}" expires in ${warning.remainingHuman} (threshold: ${warning.thresholdSeconds}s)`, { keyMasked, expiresAt: warning.expiresAt, remainingSeconds: warning.remainingSeconds, thresholdSeconds: warning.thresholdSeconds, alias: warning.alias || null });
+            this.emitWebhookAdmin('key.expiry_warning', 'system', {
+                keyMasked, keyName: warning.name, alias: warning.alias || null,
+                namespace: warning.namespace, expiresAt: warning.expiresAt,
+                remainingSeconds: warning.remainingSeconds, remainingHuman: warning.remainingHuman,
+                thresholdSeconds: warning.thresholdSeconds,
+            });
+        };
+        // Key template manager for reusable key creation presets
+        const templatesStatePath = statePath ? statePath.replace(/\.json$/, '-templates.json') : undefined;
+        this.templates = new key_templates_1.KeyTemplateManager(templatesStatePath);
+        this.metrics.registerGauge('paygate_templates_total', 'Number of key templates', () => {
+            return this.templates.count;
+        });
         // Scoped token manager (uses bootstrap admin key as signing secret, padded to min length)
         const tokenSecret = this.bootstrapAdminKey.length >= 8
             ? this.bootstrapAdminKey
@@ -298,6 +328,8 @@ class PayGateServer {
             console.log('[paygate] Redis distributed state enabled');
         }
         await this.handler.start();
+        // Start the key expiry scanner (proactive background scanning)
+        this.expiryScanner.start(() => this.gate.store.getAllRecords());
         // Plugin lifecycle: onStart
         if (this.plugins.count > 0) {
             await this.plugins.executeStart();
@@ -384,6 +416,16 @@ class PayGateServer {
                 return this.handleSetAutoTopup(req, res);
             case '/keys/usage':
                 return this.handleKeyUsage(req, res);
+            case '/keys/expiring':
+                return this.handleKeysExpiring(req, res);
+            case '/keys/templates':
+                if (req.method === 'GET')
+                    return this.handleListTemplates(req, res);
+                if (req.method === 'POST')
+                    return this.handleCreateTemplate(req, res);
+                break;
+            case '/keys/templates/delete':
+                return this.handleDeleteTemplate(req, res);
             case '/topup':
                 return this.handleTopUp(req, res);
             case '/keys/transfer':
@@ -908,6 +950,9 @@ class PayGateServer {
                 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)',
                 keyUsage: 'GET /keys/usage?key=... — Per-key usage breakdown (requires X-Admin-Key)',
+                keysExpiring: 'GET /keys/expiring?within=86400 — List keys expiring within N seconds (requires X-Admin-Key)',
+                keyTemplates: 'GET /keys/templates — List key templates + POST to create/update (requires X-Admin-Key)',
+                deleteTemplate: 'POST /keys/templates/delete — Delete a key template (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)',
@@ -1019,14 +1064,24 @@ class PayGateServer {
             res.end(JSON.stringify({ error: 'Invalid JSON' }));
             return;
         }
+        // Resolve template defaults (explicit params override template values)
+        let tpl = null;
+        if (params.template) {
+            tpl = this.templates.get(params.template);
+            if (!tpl) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: `Template "${params.template}" not found` }));
+                return;
+            }
+        }
         const name = String(params.name || 'unnamed').slice(0, 200);
-        const credits = Math.max(0, Math.floor(Number(params.credits) || 100));
+        const credits = Math.max(0, Math.floor(Number(params.credits ?? tpl?.credits ?? 100)));
         if (credits <= 0) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Credits must be a positive integer' }));
             return;
         }
-        // Calculate expiry: expiresIn (seconds) takes priority over expiresAt (ISO date)
+        // Calculate expiry: expiresIn (seconds) takes priority over expiresAt (ISO date), template TTL is fallback
         let expiresAt = null;
         if (params.expiresIn && Number(params.expiresIn) > 0) {
             expiresAt = new Date(Date.now() + Number(params.expiresIn) * 1000).toISOString();
@@ -1034,7 +1089,10 @@ class PayGateServer {
         else if (params.expiresAt) {
             expiresAt = String(params.expiresAt);
         }
-        // Parse quota if provided
+        else if (tpl && tpl.expiryTtlSeconds > 0) {
+            expiresAt = new Date(Date.now() + tpl.expiryTtlSeconds * 1000).toISOString();
+        }
+        // Parse quota: explicit params > template > undefined
         let quota = undefined;
         if (params.quota) {
             quota = {
@@ -1044,15 +1102,28 @@ class PayGateServer {
                 monthlyCreditLimit: Math.max(0, Math.floor(Number(params.quota.monthlyCreditLimit) || 0)),
             };
         }
+        else if (tpl?.quota) {
+            quota = { ...tpl.quota };
+        }
         const record = this.gate.store.createKey(name, credits, {
-            allowedTools: params.allowedTools,
-            deniedTools: params.deniedTools,
+            allowedTools: params.allowedTools || (tpl ? [...tpl.allowedTools] : undefined),
+            deniedTools: params.deniedTools || (tpl ? [...tpl.deniedTools] : undefined),
             expiresAt,
             quota,
-            tags: params.tags,
-            ipAllowlist: params.ipAllowlist,
-            namespace: params.namespace,
+            tags: params.tags || (tpl ? { ...tpl.tags } : undefined),
+            ipAllowlist: params.ipAllowlist || (tpl ? [...tpl.ipAllowlist] : undefined),
+            namespace: params.namespace || tpl?.namespace,
         });
+        // Apply template spending limit if not explicitly set
+        if (tpl && tpl.spendingLimit > 0 && record.spendingLimit === 0) {
+            record.spendingLimit = tpl.spendingLimit;
+            this.gate.store.save();
+        }
+        // Apply template auto-topup if not explicitly configured
+        if (tpl?.autoTopup && !record.autoTopup) {
+            record.autoTopup = { ...tpl.autoTopup };
+            this.gate.store.save();
+        }
         // Sync new key to Redis (if configured)
         if (this.redisSync) {
             this.redisSync.saveKey(record).catch(() => { });
@@ -2160,6 +2231,34 @@ class PayGateServer {
             ...usage,
         }, null, 2));
     }
+    // ─── /keys/expiring — List keys expiring within a time window ───────────────
+    handleKeysExpiring(req, res) {
+        if (req.method !== 'GET') {
+            res.writeHead(405, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Method not allowed' }));
+            return;
+        }
+        if (!this.checkAdmin(req, res))
+            return;
+        const urlParts = req.url?.split('?') || [];
+        const params = new URLSearchParams(urlParts[1] || '');
+        const withinStr = params.get('within');
+        const within = withinStr ? parseInt(withinStr, 10) : 86400; // Default: 24 hours
+        if (isNaN(within) || within <= 0) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid within parameter — must be a positive number of seconds' }));
+            return;
+        }
+        const allKeys = this.gate.store.getAllRecords();
+        const expiring = expiry_scanner_1.ExpiryScanner.queryExpiring(allKeys, within);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            within,
+            count: expiring.length,
+            scanner: this.expiryScanner.status,
+            keys: expiring,
+        }, null, 2));
+    }
     // ─── /keys/auto-topup — Configure auto-topup ────────────────────────────────
     async handleSetAutoTopup(req, res) {
         if (req.method !== 'POST') {
@@ -4210,11 +4309,82 @@ class PayGateServer {
         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).
-     * Fire-and-forget: errors logged, never thrown.
-     */
+    // ─── /keys/templates — CRUD ────────────────────────────────────────────────
+    handleListTemplates(req, res) {
+        if (!this.checkAdmin(req, res))
+            return;
+        const templates = this.templates.list();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ total: templates.length, templates }));
+    }
+    async handleCreateTemplate(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;
+        }
+        const name = params.name;
+        if (!name || typeof name !== 'string') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing required field: name' }));
+            return;
+        }
+        const existing = this.templates.get(name);
+        const result = this.templates.set(name, params);
+        if (!result.success) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: result.error }));
+            return;
+        }
+        const eventType = existing ? 'template.updated' : 'template.created';
+        this.audit.log(eventType, 'admin', `${existing ? 'Updated' : 'Created'} template: ${name}`, {
+            templateName: name,
+        });
+        res.writeHead(existing ? 200 : 201, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ template: result.template }));
+    }
+    async handleDeleteTemplate(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;
+        }
+        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 deleted = this.templates.delete(params.name);
+        if (!deleted) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: `Template "${params.name}" not found` }));
+            return;
+        }
+        this.audit.log('template.deleted', 'admin', `Deleted template: ${params.name}`, {
+            templateName: params.name,
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ deleted: true, name: params.name }));
+    }
     /**
      * Route admin webhook events through the WebhookRouter (for filter rules) or direct emitter.
      */
@@ -4264,6 +4434,7 @@ class PayGateServer {
         this.sessions.destroy();
         this.audit.destroy();
         this.tokens.destroy();
+        this.expiryScanner.destroy();
         if (this.redisSync) {
             await this.redisSync.destroy();
         }
@@ -4319,6 +4490,7 @@ class PayGateServer {
         this.sessions.destroy();
         this.audit.destroy();
         this.tokens.destroy();
+        this.expiryScanner.destroy();
         if (this.redisSync) {
             await this.redisSync.destroy();
         }