paygate-mcp 2.9.0 → 3.0.0

package/dist/tokens.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * ScopedTokenManager — Issue and validate short-lived scoped tokens
+ * derived from API keys.
+ *
+ * Tokens are self-contained (no server-side state): the payload is
+ * HMAC-SHA256 signed and base64url-encoded. Validation is a pure
+ * crypto check — no DB lookup needed.
+ *
+ * Format: pgt_<base64url(JSON payload)>.<base64url(HMAC signature)>
+ *
+ * Use cases:
+ *   - Browser-based agents that shouldn't hold long-lived API keys
+ *   - Temporary scoped access (e.g., only allow specific tools)
+ *   - Token delegation from a master key to a downstream agent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopedTokenManager = void 0;
+const crypto_1 = require("crypto");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const TOKEN_PREFIX = 'pgt_';
+const MAX_TTL_SECONDS = 86400; // 24 hours
+const DEFAULT_TTL_SECONDS = 3600; // 1 hour
+const MAX_TOKEN_AGE_CHECK_MS = MAX_TTL_SECONDS * 1000;
+// ─── Manager ──────────────────────────────────────────────────────────────────
+class ScopedTokenManager {
+    secret;
+    /**
+     * @param secret — Signing secret (the admin key is used by default)
+     */
+    constructor(secret) {
+        if (!secret || secret.length < 8) {
+            throw new Error('Token signing secret must be at least 8 characters');
+        }
+        this.secret = secret;
+    }
+    /**
+     * Issue a new scoped token.
+     */
+    create(options) {
+        const ttl = Math.min(Math.max(1, options.ttlSeconds || DEFAULT_TTL_SECONDS), MAX_TTL_SECONDS);
+        const expiresAt = options.expiresAt || new Date(Date.now() + ttl * 1000).toISOString();
+        const payload = {
+            apiKey: options.apiKey,
+            expiresAt,
+            issuedAt: new Date().toISOString(),
+            ...(options.allowedTools?.length ? { allowedTools: options.allowedTools } : {}),
+            ...(options.label ? { label: options.label } : {}),
+        };
+        const payloadB64 = this.base64urlEncode(JSON.stringify(payload));
+        const signature = this.sign(payloadB64);
+        return `${TOKEN_PREFIX}${payloadB64}.${signature}`;
+    }
+    /**
+     * Validate a scoped token. Returns the payload if valid.
+     */
+    validate(token) {
+        if (!token.startsWith(TOKEN_PREFIX)) {
+            return { valid: false, reason: 'not_a_scoped_token' };
+        }
+        const body = token.slice(TOKEN_PREFIX.length);
+        const dotIdx = body.lastIndexOf('.');
+        if (dotIdx === -1) {
+            return { valid: false, reason: 'malformed_token' };
+        }
+        const payloadB64 = body.slice(0, dotIdx);
+        const signatureB64 = body.slice(dotIdx + 1);
+        // Verify HMAC
+        const expectedSig = this.sign(payloadB64);
+        if (!this.timingSafeCompare(signatureB64, expectedSig)) {
+            return { valid: false, reason: 'invalid_signature' };
+        }
+        // Decode payload
+        let payload;
+        try {
+            payload = JSON.parse(this.base64urlDecode(payloadB64));
+        }
+        catch {
+            return { valid: false, reason: 'malformed_payload' };
+        }
+        // Check required fields
+        if (!payload.apiKey || !payload.expiresAt || !payload.issuedAt) {
+            return { valid: false, reason: 'missing_required_fields' };
+        }
+        // Check expiry
+        const now = Date.now();
+        const expiresAtMs = new Date(payload.expiresAt).getTime();
+        if (isNaN(expiresAtMs) || expiresAtMs <= now) {
+            return { valid: false, reason: 'token_expired' };
+        }
+        // Sanity: token can't be valid for more than MAX_TTL
+        const issuedAtMs = new Date(payload.issuedAt).getTime();
+        if (expiresAtMs - issuedAtMs > MAX_TOKEN_AGE_CHECK_MS) {
+            return { valid: false, reason: 'token_ttl_exceeded' };
+        }
+        return { valid: true, payload };
+    }
+    /**
+     * Check if a string looks like a scoped token (prefix check only).
+     */
+    static isToken(value) {
+        return value.startsWith(TOKEN_PREFIX);
+    }
+    // ─── Crypto helpers ───────────────────────────────────────────────────────
+    sign(data) {
+        const hmac = (0, crypto_1.createHmac)('sha256', this.secret);
+        hmac.update(data);
+        return this.base64urlEncode(hmac.digest());
+    }
+    timingSafeCompare(a, b) {
+        if (a.length !== b.length)
+            return false;
+        const bufA = Buffer.from(a);
+        const bufB = Buffer.from(b);
+        return (0, crypto_1.timingSafeEqual)(bufA, bufB);
+    }
+    base64urlEncode(input) {
+        const buf = typeof input === 'string' ? Buffer.from(input) : input;
+        return buf.toString('base64url');
+    }
+    base64urlDecode(input) {
+        return Buffer.from(input, 'base64url').toString('utf-8');
+    }
+}
+exports.ScopedTokenManager = ScopedTokenManager;
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paygate-mcp",
-  "version": "2.9.0",
+  "version": "3.0.0",
   "description": "Pay-per-tool-call gating proxy for MCP servers. Wrap any MCP server with API key auth, per-tool pricing, rate limiting, and usage metering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",