@payware/mcp-server 1.3.1 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payware/mcp-server",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "mcpName": "io.github.payware/mcp-server",
   "description": "Official MCP server for payware payment API integration",
   "main": "src/index.js",

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/oauth2/get-token-info.js

@@ -76,18 +76,20 @@ Auth: Requires ISV JWT token`,
           text: `📋 **OAuth2 Token Information**
 
 🔑 **Token Details:**
-- **Access Token**: ${result.access_token}
-- **Token Type**: ${result.token_type}
+- **Access Token**: ${result.accessToken}
+- **Token Type**: ${result.tokenType}
 - **Status**: ${statusEmoji[result.status]} ${result.status}
 - **Description**: ${statusDescription[result.status]}
 - **Scope**: ${result.scope}
-- **Expires**: ${result.expires_in || 'Never (client_credentials tokens do not expire)'}
+- **Expires**: ${result.expiresIn == null ? 'No expiration date' : result.expiresIn === 0 ? 'Expired - rotate with POST /oauth2/tokens/{token}/rotate' : `${result.expiresIn} seconds (~${Math.floor(result.expiresIn / 86400)} days)`}
 
-${result.status === 'GRANTED' ?
+${result.status === 'GRANTED' && result.expiresIn === 0 ?
+  '⌛ **Token has expired - rotate it with POST /oauth2/tokens/{token}/rotate (no merchant consent needed)**' :
+  result.status === 'GRANTED' ?
   '✅ **Token is ready for use in API requests**' :
   result.status === 'PENDING' ?
     '⏳ **Token is pending - wait for merchant approval**' :
-    '❌ **Token is revoked - obtain a new token**'
+    '❌ **Token is revoked, and revocation is final.** Requesting a token again returns this same revoked token; the merchant must consent again through an AUTHORIZATION_ONLY invitation (payware_isv_create_invitation)'
 }
 
 📋 **Usage Notes:**

package/src/isv/oauth2/obtain-token.js

@@ -12,7 +12,10 @@ export const obtainTokenTool = {
 ISVs must be authorized by payware registered merchants to make requests on their behalf.
 This endpoint allows ISVs to request a token using the merchant's credentials.
 
-IMPORTANT: Access tokens do not expire and only one token is allowed per merchant.
+IMPORTANT: A token requested this way expires 180 days after the merchant grants authorization.
+expiresIn in the response gives the seconds remaining (null = no expiration date). Rotate it with
+POST /oauth2/tokens/{token}/rotate, before or after expiry - no merchant consent is needed.
+Requesting again for the same merchant returns the existing token rather than a second one.
 Store tokens securely using strong encryption.
 
 Endpoint: POST /oauth2/tokens
@@ -99,7 +102,7 @@ Auth: Requires ISV JWT token with aud: "https://payware.eu"`,
 - **Token Type**: ${result.tokenType}
 - **Status**: ${result.status}
 - **Scope**: ${result.scope}
-- **Expires**: ${result.expiresIn || 'Never (client_credentials tokens do not expire)'}
+- **Expires**: ${result.expiresIn == null ? 'No expiration date' : result.expiresIn === 0 ? 'Expired - rotate with POST /oauth2/tokens/{token}/rotate' : `${result.expiresIn} seconds (~${Math.floor(result.expiresIn / 86400)} days)`}
 
 📋 **Copy this token for next operations:**
 \`${result.accessToken}\`
@@ -110,7 +113,7 @@ Auth: Requires ISV JWT token with aud: "https://payware.eu"`,
 - Use this token in the "sub" claim of future JWT requests
 
 📋 **Next Steps:**
-1. Check token status: Use token \`${result.accessToken}\` with payware_oauth2_get_token_info
+1. Check token status: Use token \`${result.accessToken}\` with payware_authorization_oauth2_get_token_info
 2. Wait for merchant approval (status will change from PENDING to GRANTED)
 3. Use this token in JWT "sub" claim for API requests to merchant data
 4. Set JWT "aud" claim to the merchant's partnerId (${finalClientId}) for API calls`
@@ -191,7 +194,6 @@ ${JSON.stringify(errorDetails, null, 2)}
 - Verify merchant partnerId (clientId) is correct
 - Ensure merchant secret is properly base64 encoded
 - Check if merchant account is active
-- Confirm no existing token for this merchant
 - Verify ISV JWT token is properly signed for OAuth2 requests`
         }]
       };

package/src/isv/oauth2/token-helper.js

@@ -54,24 +54,30 @@ Use this when you need a token but aren't sure if one exists or what it is.`,
           text: `📋 **OAuth2 Token Management Help**
 
 🔑 **About OAuth2 Tokens:**
-- Only ONE token allowed per merchant
-- Tokens don't expire (client_credentials flow)
-- Token status: PENDING → GRANTED (after merchant approval)
+- Requesting a token again for the same merchant returns the existing one, not a second one
+- Tokens requested this way expire 180 days after the merchant grants authorization
+- Rotate with POST /oauth2/tokens/{token}/rotate - works on expired tokens too, no merchant consent needed
+- Token status: PENDING → GRANTED (after merchant approval); REVOKED is final
 
 🎯 **To get your token:**
 
-**Option 1: Try creating a token**
-Use: \`payware_oauth2_obtain_token\`
-- If successful: New token will be clearly displayed
+**Option 1: Request a token**
+Use: \`payware_authorization_oauth2_obtain_token\`
+- Returns a new PENDING token, or the existing token if this merchant already has one
 - On failure the server names the reason (e.g. client not found, client disabled)
 
 **Option 2: Check a known token**
-Use: \`payware_oauth2_get_token_info\` with your saved token
-- Shows current status (PENDING/GRANTED/REVOKED)
+Use: \`payware_authorization_oauth2_get_token_info\` with your saved token
+- Shows current status (PENDING/GRANTED/REVOKED) and expiry
 
-**Option 3: Create new token (if current is lost)**
-1. Contact merchant to revoke existing token
-2. Then use \`payware_oauth2_obtain_token\` to create new one
+**Option 3: If you lost the token**
+Nothing needs revoking - the token can be retrieved:
+- Request it again with Option 1, which returns the existing token, or
+- Call GET /oauth2/tokens, which lists every token issued to your ISV with its value and status
+
+⚠️ **Never ask the merchant to revoke a token to get a new one.** Revocation is final: requesting
+again afterwards returns the same REVOKED token, and the only way back is a fresh consent through an
+AUTHORIZATION_ONLY invitation (\`payware_isv_create_invitation\`). To replace a token value, rotate it.
 
 🔐 **Security:**
 - Always store tokens securely
@@ -94,25 +100,19 @@ Use: \`payware_oauth2_get_token_info\` with your saved token
           type: 'text',
           text: `⚠️ **Token Already Exists for This Merchant**
 
-🔍 **Your existing token is stored somewhere secure** (as per OAuth2 best practices, the server doesn't return existing tokens).
+🔍 **A token already exists for this merchant, and it can be retrieved.**
 
 📋 **To find your token:**
 
-**Option 1: Check your secure storage**
-- Look where you saved tokens before
-- Environment variables file
-- Secure configuration management
-- Password manager
+**Option 1: List your tokens**
+Call GET /oauth2/tokens - it lists every token issued to your ISV with its value and status.
 
 **Option 2: If you have the token value**
-Use: \`payware_oauth2_get_token_info\` with your token to check its status
-
-**Option 3: Create new token**
-1. Contact the merchant (Partner ID: ${process.env.PAYWARE_OAUTH_CLIENT_ID || 'not configured'})
-2. Ask them to revoke the existing token
-3. Then use \`payware_oauth2_obtain_token\` to create a new one
+Use: \`payware_authorization_oauth2_get_token_info\` with your token to check its status
 
-💡 **Tip:** Always keep a secure backup of your OAuth2 tokens!
+**Option 3: Need a different value?**
+Rotate it with POST /oauth2/tokens/{token}/rotate. Do not ask the merchant to revoke it - revocation
+is final, and requesting again afterwards returns the same REVOKED token.
 
 📋 **For immediate help:**
 Run this tool with action='help' for more detailed guidance.`
@@ -138,8 +138,8 @@ ${token}
 \`\`\`
 
 🔄 **Next Steps:**
-1. **SAVE THIS TOKEN** securely (you won't be able to retrieve it later)
-2. Check status: \`payware_oauth2_get_token_info\` with token: \`${token}\`
+1. **SAVE THIS TOKEN** securely (if you lose it, GET /oauth2/tokens lists it again)
+2. Check status: \`payware_authorization_oauth2_get_token_info\` with token: \`${token}\`
 3. Wait for merchant approval (status will change to GRANTED)
 4. Use token in API requests once GRANTED`
         }]

package/src/isv/poi/cancel-price.js

@@ -61,9 +61,14 @@ export const cancelPOIPriceTool = {
 
 **ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
 **Endpoint:** DELETE /poi/{poiId}/price
-**Use Case:** Cancel a price that was set but customer didn't pay (e.g., order cancelled).
+**Use Case:** Cancel a price that was set but not yet scanned (e.g., order cancelled).
 
-The POI will return to IDLE state and be ready for a new price.
+The POI returns to IDLE and is ready for a new price.
+
+**Only before the scan.** The scan is the customer's bank processing the payment, so from then on a POI
+sale cannot be cancelled by the merchant or an ISV, on any plan: this answers 409
+ERR_POI_NO_PENDING_PAYMENT, and cancelling the transaction itself answers 409 ERR_ALREADY_PROCESSED. The
+sale completes or expires; the POI accepts the next price meanwhile.
 
 **Required:** POI ID, Merchant Partner ID, and OAuth2 token.`,
 

package/src/isv/poi/get-poi.js

@@ -115,8 +115,7 @@ export const getPOITool = {
       const statusEmoji = {
         'IDLE': '🟢',
         'READY': '🟡',
-        'BUSY': '🔴',
-        'DISABLED': '⚫'
+        'BUSY': '🔴'
       }[poi.status] || '⚪';
 
       return {
@@ -137,7 +136,7 @@ export const getPOITool = {
 - Linked vPOS: ${poi.linkedVposCount || 0} terminals
 
 **Current Session:**
-${poi.status !== 'IDLE' && poi.pendingAmount ? `- Amount: ${poi.pendingAmount} ${poi.pendingCurrency}
+${poi.status === 'READY' && poi.pendingAmount ? `- Amount: ${poi.pendingAmount} ${poi.pendingCurrency}
 - Expires: ${poi.sessionExpiresAt || 'N/A'}
 - Token: ${poi.sessionToken || 'N/A'}` : '- No active session'}