@payware/mcp-server 1.3.0 → 1.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 payware LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,8 @@
 
 Official MCP (Model Context Protocol) server for payware payment API integration. This server enables AI assistants to interact with payware APIs, automating integration workflows for all partner types.
 
+Releases are published to npm as `@payware/mcp-server` and to the official [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.payware/mcp-server`. MIT licensed, see [LICENSE](LICENSE).
+
 ## Who Is This For?
 
 - **Merchants** - Accept payments, manage products, generate transaction reports

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@payware/mcp-server",
-  "version": "1.3.0",
+  "version": "1.3.2",
+  "mcpName": "io.github.payware/mcp-server",
   "description": "Official MCP server for payware payment API integration",
   "main": "src/index.js",
   "type": "module",
@@ -36,15 +37,18 @@
     "model-context-protocol",
     "payware",
     "payments",
-    "payment-gateway",
-    "payment-processing",
     "api",
     "fintech",
     "pos",
     "terminal",
     "merchant",
     "isv",
-    "oauth2"
+    "oauth2",
+    "a2a-payments",
+    "account-to-account",
+    "instant-payments",
+    "transaction-resolution",
+    "qr-code-payments"
   ],
   "author": "payware <support@payware.com>",
   "license": "MIT",

package/src/auth/sandbox-setup.js

@@ -76,7 +76,7 @@ export function generateSandboxConfig(partnerId, privateKey = null) {
       type: 'JWT',
       algorithm: 'RS256',
       audience: 'https://payware.eu',
-      requiresContentMd5: 'For POST/PUT/PATCH requests',
+      requiresContentSha256: 'For POST/PUT/PATCH requests: Base64(SHA-256(body)) in the JWT header',
       hasPrivateKey: !!privateKey
     },
     generatedAt: new Date().toISOString()

package/src/core/auth/jwt-token.js

@@ -30,26 +30,6 @@ export function generateContentSha256(body) {
   return hash.digest('base64');
 }
 
-/**
- * Generate MD5 hash for JWT contentMd5 header (DEPRECATED - use generateContentSha256)
- *
- * @deprecated Use generateContentSha256 instead. MD5 is still supported by the server
- * for backwards compatibility but is deprecated.
- *
- * @param {Object|string} body - Request body (object will be consistently serialized)
- * @returns {string} Base64 encoded MD5 hash for JWT contentMd5 header
- */
-export function generateContentMd5(body) {
-  if (!body) return null;
-
-  const bodyString = typeof body === 'string' ? body : createDeterministicJSON(body);
-
-  // Generate MD5 hash as raw binary and encode in base64
-  const hash = crypto.createHash('md5');
-  hash.update(bodyString, 'utf8');
-  return hash.digest('base64');
-}
-
 /**
  * Generate the exact JSON string for both JWT content hash and HTTP request body
  *
@@ -143,9 +123,16 @@ export function createRequestSignature(method, path, body, privateKey) {
 /**
  * Validate and debug JWT token implementation
  */
+// The rules below mirror the payware API's authentication checks. A check that is looser
+// than the server's reports a token as valid that the API refuses; one that is stricter fails tokens the
+// API accepts - the audience check did both kinds of harm until it learned the on-behalf form.
+const PAYWARE_AUDIENCE = 'https://payware.eu';
+const IAT_MAX_AGE_SECONDS = 300;
+const IAT_MAX_FUTURE_SKEW_SECONDS = 60;
+
 export const validateJWTTokenTool = {
   name: "payware_authentication_validate_jwt",
-  description: "Validate and debug JWT token structure, decode payload/headers, verify content hash (SHA-256/MD5) calculation, and check RS256 signature format for payware API compliance",
+  description: "Validate and debug a payware JWT: decode header and payload, check the claims against the API's rules (algorithm, audience including the ISV on-behalf form, 5-minute freshness), and verify the contentSha256 hash against the request body when one is given",
   inputSchema: {
     type: "object",
     properties: {
@@ -155,7 +142,7 @@ export const validateJWTTokenTool = {
       },
       expectedPayload: {
         type: "object",
-        description: "Expected request body (optional - for content hash validation)"
+        description: "The request body the token was made for (optional). Give it for POST, PUT and PATCH: contentSha256 is then required and checked against it. Leave it out for GET and DELETE, which carry no hash."
       }
     },
     required: ["jwtToken"],
@@ -179,55 +166,76 @@ export const validateJWTTokenTool = {
 
       const { header, payload } = decoded;
 
-      // Determine which hash type is used
+      // Only contentSha256 counts. The server stopped accepting contentMd5 (SEC-013): a token that
+      // carries only contentMd5 is answered 401 ERR_MISSING_CONTENT_HASH, so reporting it here as a
+      // present, matching hash told an integrator a token was fine that the API would refuse.
       const hasContentSha256 = !!header.contentSha256;
       const hasContentMd5 = !!header.contentMd5;
-      const hasContentHash = hasContentSha256 || hasContentMd5;
+      const hasContentHash = hasContentSha256;
+
+      // Audience. https://payware.eu for a direct call, and always on /oauth2. An ISV acting on behalf
+      // of a merchant sets aud to that merchant's partner ID and must then carry sub = the merchant's
+      // OAuth token - the server answers ERR_MISSING_TOKEN without it. Only accepting
+      // https://payware.eu failed every on-behalf token, which is most of what an ISV sends.
+      const onBehalf = typeof payload.aud === 'string' && payload.aud !== '' && payload.aud !== PAYWARE_AUDIENCE;
+      const hasSubject = typeof payload.sub === 'string' && payload.sub.trim() !== '';
+
+      // Freshness. The server refuses a token issued more than 5 minutes ago, or more than 60 seconds
+      // in the future (ERR_STALE_TOKEN); a missing iat is reported by issuedAt.
+      const ageSeconds = payload.iat ? Math.floor(Date.now() / 1000) - payload.iat : null;
+      const stale = ageSeconds !== null && ageSeconds > IAT_MAX_AGE_SECONDS;
+      const fromTheFuture = ageSeconds !== null && ageSeconds < -IAT_MAX_FUTURE_SKEW_SECONDS;
 
       // Validation results
       const validation = {
         structure: true,
         algorithm: header.alg === 'RS256',
         type: header.typ === 'JWT',
-        audience: payload.aud === 'https://payware.eu',
+        audience: payload.aud === PAYWARE_AUDIENCE || (onBehalf && hasSubject),
         issuer: !!payload.iss,
         issuedAt: !!payload.iat,
-        contentHash: hasContentHash
+        freshness: !stale && !fromTheFuture,
+        // Required only on a request with a body. Without expectedPayload this tool cannot tell a GET
+        // from a POST, so an absent hash is not a failure on its own - it used to fail every GET token
+        // while the report beside it said "OK for GET requests".
+        contentHash: expectedPayload ? hasContentHash : true
       };
 
       // Content hash validation if expected payload provided
       let hashValidation = null;
       if (expectedPayload && hasContentHash) {
-        if (hasContentSha256) {
-          const calculatedSha256 = generateContentSha256(expectedPayload);
-          hashValidation = {
-            type: 'SHA-256 (preferred)',
-            provided: header.contentSha256,
-            calculated: calculatedSha256,
-            matches: header.contentSha256 === calculatedSha256,
-            deterministicJson: createDeterministicJSON(expectedPayload)
-          };
-        } else if (hasContentMd5) {
-          const calculatedMd5 = generateContentMd5(expectedPayload);
-          hashValidation = {
-            type: 'MD5 (deprecated)',
-            provided: header.contentMd5,
-            calculated: calculatedMd5,
-            matches: header.contentMd5 === calculatedMd5,
-            deterministicJson: createDeterministicJSON(expectedPayload)
-          };
-        }
+        const calculatedSha256 = generateContentSha256(expectedPayload);
+        hashValidation = {
+          type: 'SHA-256',
+          provided: header.contentSha256,
+          calculated: calculatedSha256,
+          matches: header.contentSha256 === calculatedSha256,
+          deterministicJson: createDeterministicJSON(expectedPayload)
+        };
       }
 
       // Check for common issues
       const issues = [];
       if (!validation.algorithm) issues.push("Algorithm should be 'RS256'");
       if (!validation.type) issues.push("Type should be 'JWT'");
-      if (!validation.audience) issues.push("Audience should be 'https://payware.eu'");
+      if (!payload.aud) {
+        issues.push("Missing audience (aud) claim");
+      } else if (onBehalf && !hasSubject) {
+        issues.push(`aud is a merchant partner ID (${payload.aud}), which means acting on its behalf, but sub is missing - set sub to that merchant's OAuth token (ERR_MISSING_TOKEN), or use aud = ${PAYWARE_AUDIENCE} for a direct call`);
+      }
       if (!validation.issuer) issues.push("Missing issuer (iss) claim");
       if (!validation.issuedAt) issues.push("Missing issued at (iat) claim");
+      if (stale) {
+        issues.push(`Token is stale: issued ${ageSeconds}s ago, and the API accepts tokens up to ${IAT_MAX_AGE_SECONDS}s old (ERR_STALE_TOKEN)`);
+      }
+      if (fromTheFuture) {
+        issues.push(`iat is ${-ageSeconds}s in the future, beyond the ${IAT_MAX_FUTURE_SKEW_SECONDS}s of clock skew the API tolerates (ERR_STALE_TOKEN)`);
+      }
+      if (expectedPayload && !hasContentSha256 && !hasContentMd5) {
+        issues.push("Missing contentSha256: a request with a body must carry Base64(SHA-256(body)) in the JWT header (ERR_MISSING_CONTENT_HASH)");
+      }
       if (hasContentMd5 && !hasContentSha256) {
-        issues.push("Using deprecated MD5 hash - consider upgrading to SHA-256 (contentSha256)");
+        issues.push("contentMd5 is not accepted: the API answers 401 ERR_MISSING_CONTENT_HASH. Send contentSha256 = Base64(SHA-256(body)) instead");
       }
       if (hashValidation && !hashValidation.matches) {
         issues.push("Content hash mismatch - ensure deterministic JSON serialization with sorted keys");
@@ -259,10 +267,11 @@ ${JSON.stringify(payload, null, 2)}
 ${validation.structure ? '✅' : '❌'} **Structure**: JWT has valid 3-part structure
 ${validation.algorithm ? '✅' : '❌'} **Algorithm**: RS256 ${validation.algorithm ? '(correct)' : `(found: ${header.alg})`}
 ${validation.type ? '✅' : '❌'} **Type**: JWT ${validation.type ? '(correct)' : `(found: ${header.typ})`}
-${validation.audience ? '✅' : '❌'} **Audience**: https://payware.eu ${validation.audience ? '(correct)' : `(found: ${payload.aud})`}
+${validation.audience ? '✅' : '❌'} **Audience**: ${payload.aud === PAYWARE_AUDIENCE ? `${PAYWARE_AUDIENCE} (direct call)` : onBehalf ? `${payload.aud} (on behalf of this merchant, sub ${hasSubject ? 'present' : 'MISSING'}; not valid on /oauth2 endpoints, which need ${PAYWARE_AUDIENCE})` : 'Missing'}
 ${validation.issuer ? '✅' : '❌'} **Issuer**: ${payload.iss || 'Missing'}
 ${validation.issuedAt ? '✅' : '❌'} **Issued At**: ${payload.iat ? new Date(payload.iat * 1000).toISOString() : 'Missing'}
-${validation.contentHash ? '✅' : 'ℹ️'} **Content Hash**: ${header.contentSha256 ? `SHA-256: ${header.contentSha256}` : header.contentMd5 ? `MD5 (deprecated): ${header.contentMd5}` : 'Not present (OK for GET requests)'}
+${validation.freshness ? '✅' : '❌'} **Freshness**: ${ageSeconds === null ? 'n/a' : stale ? `stale - ${ageSeconds}s old, limit ${IAT_MAX_AGE_SECONDS}s` : fromTheFuture ? `${-ageSeconds}s in the future, limit ${IAT_MAX_FUTURE_SKEW_SECONDS}s` : `${ageSeconds}s old (limit ${IAT_MAX_AGE_SECONDS}s)`}
+${header.contentSha256 ? '✅' : validation.contentHash ? 'ℹ️' : '❌'} **Content Hash**: ${header.contentSha256 ? `SHA-256: ${header.contentSha256}` : header.contentMd5 ? `only contentMd5, which the API rejects - send contentSha256` : expectedPayload ? 'Missing - required on a request with a body' : 'Not present (fine for GET and DELETE; required on POST, PUT and PATCH with a body)'}
 
 ${hashValidation ? `## Content Hash Validation
 
@@ -305,7 +314,8 @@ ${issues.map(issue => `- ${issue}`).join('\n')}
 
 ${issues.includes("Algorithm should be 'RS256'") ? '- Update JWT algorithm to RS256\n' : ''}
 ${issues.includes("Type should be 'JWT'") ? '- Set JWT type to "JWT"\n' : ''}
-${issues.includes("Audience should be 'https://payware.eu'") ? '- Set audience to "https://payware.eu" (not just "payware")\n' : ''}
+${!validation.audience ? `- Set aud to "${PAYWARE_AUDIENCE}" for a direct call, or to the merchant's partner ID together with sub = its OAuth token when acting on its behalf\n` : ''}
+${!validation.freshness ? '- Create the JWT immediately before each request: the API accepts it for 5 minutes, and check the clock of the machine that signs it\n' : ''}
 ${issues.includes("Missing issuer (iss) claim") ? '- Add your partner ID as the issuer claim\n' : ''}
 ${issues.includes("Missing issued at (iat) claim") ? '- Add current Unix timestamp as issued at claim\n' : ''}
 ${issues.some(i => i.includes('hash mismatch')) ? '- Use deterministic JSON serialization with sorted keys\n- Ensure same JSON string for hash calculation and HTTP body\n' : ''}
@@ -550,7 +560,7 @@ ${deterministicJson}
 ❌ Setting audience to "payware" instead of "https://payware.eu"
 ❌ Putting contentSha256 in payload instead of header
 ❌ Using wrong algorithm (HS256 instead of RS256)
-❌ Using deprecated contentMd5 instead of contentSha256
+❌ Sending contentMd5 - the API no longer accepts it; use contentSha256
 
 ---
 **Execution Info:**

package/src/isv/invitations/index.js

@@ -350,7 +350,8 @@ ${rows || 'No invitations match this filter.'}
 
 **Status meanings:** ⏳ PENDING - link sent, merchant has not acted. ✅ COMPLETED - merchant accepted;
 obtain a token with \`payware_authorization_oauth2_obtain_token\`. ⌛ EXPIRED - the link lapsed; create
-a new invitation. 🚫 CANCELLED - withdrawn by you.
+a new invitation. 🚫 CANCELLED - withdrawn by you, or by payware because the merchant it was addressed
+to was deleted.
 
 **Request ID:** ${result.requestId || 'N/A'}
 **Timestamp:** ${result.timestamp}`

package/src/isv/products/create-product.js

@@ -70,7 +70,7 @@ export const createProductTool = {
       },
       shop: {
         type: "string",
-        description: "Shop code (if not supplied, default shop is used)",
+        description: "Shop code. If omitted, the merchant's default shop is used - which may be outside your assigned scope (403 ERR_SHOP_NOT_IN_SCOPE). Find valid codes with payware_shops_list.",
         maxLength: 10
       },
       // Product Data Properties

package/src/merchant/transactions/create-transaction.js

@@ -1,5 +1,5 @@
 import axios from 'axios';
-import { createJWTToken, generateContentMd5 } from '../../core/auth/jwt-token.js';
+import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 

package/src/proxy-server.js

@@ -25,9 +25,16 @@ class PaywareMCPProxy {
   }
 
   setupMiddleware() {
-    // Enable CORS for all routes
+    // SEC-018: CORS was `origin: true` with credentials - it reflected ANY requesting origin, so any
+    // web page the operator visited could drive these routes from their browser. The routes below
+    // mint JWTs with the configured partner's private key and call the payware API as that partner,
+    // so this is not a cosmetic default. Restricted to explicit local origins; set
+    // PAYWARE_MCP_PROXY_ORIGINS (comma-separated) to widen it deliberately.
+    const allowedOrigins = (process.env.PAYWARE_MCP_PROXY_ORIGINS
+      || `http://localhost:${this.port},http://127.0.0.1:${this.port}`)
+      .split(',').map((o) => o.trim()).filter(Boolean);
     this.app.use(cors({
-      origin: true,
+      origin: allowedOrigins,
       credentials: true
     }));
     
@@ -168,8 +175,22 @@ class PaywareMCPProxy {
   }
 
   async start() {
-    this.app.listen(this.port, '0.0.0.0', () => {
-      console.log(`🚀 payware MCP Proxy Server running on http://0.0.0.0:${this.port}`);
+    // SEC-018: loopback by default. This bound 0.0.0.0 - every interface - with no authentication on
+    // /tools, /tools/:toolName or /mcp, each of which spawns the MCP server with the process env
+    // (PAYWARE_PARTNER_ID and the sandbox/production private key paths) and can therefore sign as
+    // that partner. On a shared dev host or an office LAN that is partner impersonation over plain
+    // HTTP, and with a production key it is total. The stdio transport (mcp-proxy.js) is the normal
+    // path and opens no socket at all.
+    //
+    // A wider bind is now an explicit opt-in via PAYWARE_MCP_PROXY_HOST, so exposing it is a
+    // decision someone made rather than the default they inherited.
+    const host = process.env.PAYWARE_MCP_PROXY_HOST || '127.0.0.1';
+    if (host !== '127.0.0.1' && host !== 'localhost') {
+      console.warn(`⚠️  MCP proxy binding ${host} - these routes are UNAUTHENTICATED and can sign as `
+        + `the configured partner. Only do this on a network you control.`);
+    }
+    this.app.listen(this.port, host, () => {
+      console.log(`🚀 payware MCP Proxy Server running on http://${host}:${this.port}`);
       console.log(`📚 API Documentation: http://localhost:${this.port}`);
       console.log(`🔧 Health Check: http://localhost:${this.port}/health`);
       console.log(`🛠️  Tools List: http://localhost:${this.port}/tools`);