@payware/mcp-server 1.0.0

package/src/utils/format-request.js

@@ -0,0 +1,363 @@
+/**
+ * Format and validate requests for payware API with deterministic JSON serialization
+ */
+
+import { createMinimizedJSON } from '../core/utils/json-serializer.js';
+
+/**
+ * Format transaction request data
+ * @param {Object} data - Raw transaction data
+ * @returns {Object} Formatted and validated transaction data
+ */
+export function formatTransactionRequest(data) {
+  const {
+    type = 'PLAIN',
+    amount,
+    currency = 'EUR',
+    reasonL1,
+    reasonL2,
+    callbackUrl,
+    account,
+    friendlyName,
+    shop,
+    timeToLive = 120,
+    passbackParams
+  } = data;
+  
+  // Validation
+  const errors = [];
+  
+  // reasonL1 is required
+  if (!reasonL1 || typeof reasonL1 !== 'string' || reasonL1.trim().length === 0) {
+    errors.push('reasonL1 is required (transaction grounds description)');
+  }
+  
+  if (reasonL1 && reasonL1.length > 100) {
+    errors.push('reasonL1 cannot exceed 100 characters');
+  }
+  
+  if (reasonL2 && reasonL2.length > 100) {
+    errors.push('reasonL2 cannot exceed 100 characters');
+  }
+  
+  // Amount validation (optional for flexible amounts)
+  if (amount !== undefined && (typeof amount !== 'number' && typeof amount !== 'string')) {
+    errors.push('Amount must be a number or string representing currency value');
+  }
+  
+  if (amount !== undefined && parseFloat(amount) < 0) {
+    errors.push('Amount must be non-negative currency value');
+  }
+  
+  // Amount can be any positive value (limited by Java type implementation)
+  
+  if (!['PLAIN', 'QR', 'BARCODE'].includes(type)) {
+    errors.push('Transaction type must be PLAIN, QR, or BARCODE');
+  }
+  
+  // Currency validation - accept any 3-character ISO code
+  if (!currency || typeof currency !== 'string' || !currency.match(/^[A-Z]{3}$/)) {
+    errors.push('Currency must be a valid ISO 3-character code (e.g., EUR, USD, JPY)');
+  }
+  
+  if (callbackUrl && !callbackUrl.match(/^https?:\/\/.+/)) {
+    errors.push('Callback URL must be a valid HTTP/HTTPS URL');
+  }
+  
+  if (account && account.length > 36) {
+    errors.push('Account identifier cannot exceed 36 characters');
+  }
+  
+  if (friendlyName && friendlyName.length > 100) {
+    errors.push('Friendly name cannot exceed 100 characters');
+  }
+  
+  if (shop && shop.length > 10) {
+    errors.push('Shop code cannot exceed 10 characters');
+  }
+  
+  if (timeToLive && (timeToLive < 60 || timeToLive > 600)) {
+    errors.push('Time to live must be between 60 and 600 seconds');
+  }
+  
+  if (errors.length > 0) {
+    throw new Error(`Validation errors: ${errors.join(', ')}`);
+  }
+  
+  // Format the request according to documentation structure
+  const formattedRequest = {
+    ...(account && { account }),
+    ...(friendlyName && { friendlyName }),
+    ...(shop && { shop }),
+    ...(callbackUrl && { callbackUrl }),
+    ...(passbackParams && { passbackParams }),
+    trData: {
+      amount: amount !== undefined ? amount.toString() : '0.00',
+      currency,
+      reasonL1,
+      ...(reasonL2 && { reasonL2 })
+    },
+    trOptions: {
+      type,
+      timeToLive
+    }
+  };
+  
+  return {
+    request: formattedRequest,
+    validation: {
+      valid: true,
+      errors: [],
+      warnings: []
+    },
+    formatted: true,
+    timestamp: new Date().toISOString()
+  };
+}
+
+/**
+ * Format API headers
+ * @param {string} jwtToken - JWT authentication token
+ * @param {string} signature - Request signature (optional)
+ * @returns {Object} Formatted headers
+ */
+export function formatAPIHeaders(jwtToken, signature = null) {
+  const headers = {
+    'Authorization': `Bearer ${jwtToken}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1',
+    'Accept': 'application/json'
+  };
+  
+  if (signature) {
+    headers['X-Signature'] = signature;
+  }
+  
+  return headers;
+}
+
+/**
+ * Format curl command for API testing
+ * @param {string} method - HTTP method
+ * @param {string} endpoint - API endpoint
+ * @param {Object} headers - Request headers
+ * @param {Object} body - Request body (optional)
+ * @returns {string} Formatted curl command
+ */
+export function formatCurlCommand(method, endpoint, headers, body = null) {
+  let curl = `curl -X ${method.toUpperCase()} "${endpoint}"`;
+  
+  // Add headers
+  Object.entries(headers).forEach(([key, value]) => {
+    curl += ` \\\n  -H "${key}: ${value}"`;
+  });
+  
+  // Add body if present
+  if (body) {
+    curl += ` \\\n  -d '${JSON.stringify(body, null, 2)}'`;
+  }
+  
+  return curl;
+}
+
+/**
+ * Format request tool implementation
+ */
+export const formatRequestTool = {
+  name: "payware_utils_format_request",
+  description: "Format and validate payware API requests with proper structure and headers",
+  inputSchema: {
+    type: "object",
+    properties: {
+      type: {
+        type: "string",
+        enum: ["transaction", "headers", "curl"],
+        description: "Type of formatting to perform"
+      },
+      data: {
+        type: "object",
+        description: "Data to format (structure depends on type)"
+      },
+      jwtToken: {
+        type: "string",
+        description: "JWT token for header formatting"
+      },
+      signature: {
+        type: "string",
+        description: "Request signature (optional)"
+      },
+      endpoint: {
+        type: "string",
+        description: "API endpoint URL (for curl formatting)"
+      },
+      method: {
+        type: "string",
+        enum: ["GET", "POST", "PUT", "DELETE"],
+        description: "HTTP method (for curl formatting)"
+      }
+    },
+    required: ["type"],
+    additionalProperties: false
+  },
+  
+  async handler(args) {
+    const { type, data = {}, jwtToken, signature, endpoint, method = 'POST' } = args;
+    
+    switch (type) {
+      case 'transaction': {
+        if (!data.amount) {
+          throw new Error("Amount is required for transaction formatting");
+        }
+        
+        const formatted = formatTransactionRequest(data);
+        
+        const minimizedJSON = createMinimizedJSON(formatted.request);
+        
+        return {
+          content: [{
+            type: "text",
+            text: `📋 **Transaction Request Formatted**
+
+**Formatted Request (Pretty):**
+\`\`\`json
+${JSON.stringify(formatted.request, null, 2)}
+\`\`\`
+
+**Minimized JSON (API Format):**
+\`\`\`json
+${minimizedJSON}
+\`\`\`
+
+**Validation Result:**
+- ✅ Valid: ${formatted.validation.valid}
+- Errors: ${formatted.validation.errors.length}
+- Warnings: ${formatted.validation.warnings.length}
+
+**Request Details:**
+- Type: ${formatted.request.trOptions.type}
+- Amount: ${formatted.request.trData.amount} ${formatted.request.trData.currency}
+- Description: ${formatted.request.trData.reasonL1}
+${formatted.request.trData.reasonL2 ? `- Description L2: ${formatted.request.trData.reasonL2}` : ''}
+${formatted.request.callbackUrl ? `- Callback URL: ${formatted.request.callbackUrl}` : ''}
+
+**Usage:**
+Use the minimized JSON format for API calls to ensure MD5 consistency:
+\`\`\`javascript
+const response = await fetch('https://sandbox.payware.eu/api/transactions', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer YOUR_JWT_TOKEN',
+    'Content-Type': 'application/json'
+  },
+  body: '${minimizedJSON}'  // Use pre-minimized string for MD5 consistency
+});
+\`\`\`
+
+**⚠️ Important:** Always use the minimized JSON format to ensure the MD5 hash in your JWT token matches the request body.
+
+**Formatted:** ${formatted.formatted}
+**Timestamp:** ${formatted.timestamp}`
+          }]
+        };
+      }
+      
+      case 'headers': {
+        if (!jwtToken) {
+          throw new Error("JWT token is required for header formatting");
+        }
+        
+        const headers = formatAPIHeaders(jwtToken, signature);
+        
+        return {
+          content: [{
+            type: "text",
+            text: `📋 **API Headers Formatted**
+
+**Headers:**
+\`\`\`json
+${JSON.stringify(headers, null, 2)}
+\`\`\`
+
+**Header Breakdown:**
+- **Authorization**: Bearer token for authentication
+- **Content-Type**: JSON content type
+- **Accept**: Expects JSON response
+${signature ? '- **X-Signature**: Request signature for additional security' : ''}
+
+**Usage in JavaScript:**
+\`\`\`javascript
+const headers = ${JSON.stringify(headers, null, 2)};
+
+fetch(url, { headers, ...options });
+\`\`\`
+
+**Usage in Python:**
+\`\`\`python
+headers = ${JSON.stringify(headers, null, 2).replace(/"/g, "'")}
+
+requests.post(url, headers=headers, json=data)
+\`\`\`
+
+**Usage in cURL:**
+\`\`\`bash
+${Object.entries(headers).map(([key, value]) => `curl -H "${key}: ${value}"`).join(' \\\n')} \\
+  https://sandbox.payware.eu/api/transactions
+\`\`\``
+          }]
+        };
+      }
+      
+      case 'curl': {
+        if (!endpoint) {
+          throw new Error("Endpoint is required for curl formatting");
+        }
+        
+        if (!jwtToken) {
+          throw new Error("JWT token is required for curl formatting");
+        }
+        
+        const headers = formatAPIHeaders(jwtToken, signature);
+        const curl = formatCurlCommand(method, endpoint, headers, data);
+        
+        return {
+          content: [{
+            type: "text",
+            text: `💻 **cURL Command Generated**
+
+**Command:**
+\`\`\`bash
+${curl}
+\`\`\`
+
+**Command Breakdown:**
+- Method: ${method.toUpperCase()}
+- Endpoint: ${endpoint}
+- Headers: ${Object.keys(headers).length} headers included
+${data && Object.keys(data).length > 0 ? `- Body: JSON payload included` : '- Body: No payload'}
+
+**Usage:**
+1. Copy the command above
+2. Paste it into your terminal
+3. Execute to test the API call directly
+4. Modify parameters as needed
+
+**Response:**
+The command will return the API response directly in your terminal, including:
+- HTTP status code
+- Response headers  
+- JSON response body
+- Any error messages
+
+**Tips:**
+- Add \`-v\` flag for verbose output with headers
+- Add \`-i\` flag to include response headers
+- Use \`-o filename\` to save response to file`
+          }]
+        };
+      }
+      
+      default:
+        throw new Error(`Unknown formatting type: ${type}`);
+    }
+  }
+};

package/src/utils/json-formatter.js

@@ -0,0 +1,249 @@
+/**
+ * JSON formatter utility for deterministic serialization
+ * Helps developers format JSON correctly for payware API requests
+ */
+
+import { createDeterministicJSON, validateJSONConsistency } from '../core/utils/json-serializer.js';
+import { generateContentMd5 } from '../core/auth/jwt-token.js';
+
+/**
+ * Format JSON with deterministic serialization tool
+ */
+export const formatJSONDeterministicTool = {
+  name: "payware_utils_format_json_deterministic",
+  description: "Format JSON payload with deterministic key sorting for consistent MD5 calculation and payware API compliance",
+  inputSchema: {
+    type: "object",
+    properties: {
+      payload: {
+        type: "object",
+        description: "JSON payload to format with deterministic serialization"
+      },
+      showComparison: {
+        type: "boolean",
+        description: "Show comparison between standard and deterministic JSON",
+        default: true
+      },
+      calculateMD5: {
+        type: "boolean",
+        description: "Calculate MD5 hash for JWT contentMd5 usage",
+        default: true
+      },
+      validateConsistency: {
+        type: "boolean",
+        description: "Validate that multiple serializations produce the same result",
+        default: false
+      }
+    },
+    required: ["payload"],
+    additionalProperties: false
+  },
+
+  async handler(args) {
+    const {
+      payload,
+      showComparison = true,
+      calculateMD5 = true,
+      validateConsistency = false
+    } = args;
+
+    if (!payload || typeof payload !== 'object') {
+      throw new Error("Payload must be a valid JSON object");
+    }
+
+    try {
+      // Generate different serializations
+      const standardJson = JSON.stringify(payload);
+      const prettyJson = JSON.stringify(payload, null, 2);
+      const deterministicJson = createDeterministicJSON(payload);
+
+      // Calculate MD5 hash
+      const md5Hash = calculateMD5 ? generateContentMd5(payload) : null;
+
+      // Get key ordering information
+      const originalKeys = Object.keys(payload);
+      const sortedKeys = [...originalKeys].sort();
+      const isAlreadySorted = JSON.stringify(originalKeys) === JSON.stringify(sortedKeys);
+
+      // Consistency validation
+      let consistencyTest = null;
+      if (validateConsistency) {
+        // Create multiple instances and test consistency
+        const testPayload1 = { ...payload };
+        const testPayload2 = JSON.parse(JSON.stringify(payload));
+        const testPayload3 = Object.assign({}, payload);
+
+        consistencyTest = {
+          test1: createDeterministicJSON(testPayload1),
+          test2: createDeterministicJSON(testPayload2),
+          test3: createDeterministicJSON(testPayload3),
+          allMatch: validateJSONConsistency(testPayload1, testPayload2) &&
+                   validateJSONConsistency(testPayload2, testPayload3)
+        };
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `📋 **JSON Deterministic Formatter**
+
+## Input Payload Analysis
+
+**Original Key Order**: [${originalKeys.join(', ')}]
+**Sorted Key Order**: [${sortedKeys.join(', ')}]
+**Already Sorted**: ${isAlreadySorted ? '✅ Yes' : '❌ No (will be reordered)'}
+
+${showComparison ? `## JSON Serialization Comparison
+
+**❌ Standard JSON.stringify()** (property order varies):
+\`\`\`json
+${standardJson}
+\`\`\`
+
+**📖 Pretty JSON** (formatted but inconsistent order):
+\`\`\`json
+${prettyJson}
+\`\`\`
+
+**✅ Deterministic JSON** (sorted keys, consistent):
+\`\`\`json
+${deterministicJson}
+\`\`\`
+
+### Key Differences:
+${isAlreadySorted ?
+  '- ✅ Your object keys are already in sorted order' :
+  `- ❌ Keys will be reordered: ${originalKeys.join(' → ')} becomes ${sortedKeys.join(' → ')}`}
+- ✅ Deterministic JSON ensures consistent serialization across platforms
+- ✅ Required for accurate MD5 hash calculation in JWT tokens
+` : ''}
+
+## ✅ **payware API Ready JSON**
+
+Use this exact JSON string for both JWT MD5 calculation and HTTP request body:
+
+\`\`\`json
+${deterministicJson}
+\`\`\`
+
+${calculateMD5 ? `## 🔒 **MD5 Hash for JWT**
+
+**contentMd5**: \`${md5Hash}\`
+
+**Usage in JWT Header**:
+\`\`\`json
+{
+  "alg": "RS256",
+  "typ": "JWT",
+  "contentMd5": "${md5Hash}"
+}
+\`\`\`
+` : ''}
+
+## 🛠 **Implementation Guide**
+
+### Python Implementation:
+\`\`\`python
+import json
+
+# CORRECT: Use deterministic JSON
+json_body = json.dumps(payload, sort_keys=True, separators=(',', ':'))
+jwt_token = create_jwt_token(json_body)
+response = requests.post(url, data=json_body, headers=headers)
+\`\`\`
+
+### Node.js Implementation:
+\`\`\`javascript
+// Helper function for deterministic JSON
+function createDeterministicJSON(obj) {
+  return JSON.stringify(obj, Object.keys(obj).sort());
+}
+
+// CORRECT: Use deterministic JSON
+const jsonBody = createDeterministicJSON(payload);
+const jwtToken = createJWTToken(jsonBody);
+const response = await axios.post(url, jsonBody, {headers});
+\`\`\`
+
+### PHP Implementation:
+\`\`\`php
+// CORRECT: Use deterministic JSON
+function createDeterministicJSON($obj) {
+    ksort($obj);
+    return json_encode($obj, JSON_UNESCAPED_SLASHES);
+}
+
+$jsonBody = createDeterministicJSON($payload);
+$jwtToken = createJWTToken($jsonBody);
+// Use $jsonBody for both JWT and cURL request
+\`\`\`
+
+${consistencyTest ? `## 🧪 **Consistency Validation**
+
+**Test Results**:
+- Test 1: \`${consistencyTest.test1}\`
+- Test 2: \`${consistencyTest.test2}\`
+- Test 3: \`${consistencyTest.test3}\`
+
+**All Match**: ${consistencyTest.allMatch ? '✅ Consistent' : '❌ Inconsistent'}
+
+${!consistencyTest.allMatch ? '⚠️ **Warning**: Inconsistent serialization detected. This could cause MD5 mismatches.' : ''}
+` : ''}
+
+## ⚠️ **PAYWARE Critical Requirements**
+
+1. **Same String Requirement**: The EXACT same compact JSON string must be used for both JWT contentMd5 and HTTP request body
+2. **Compact Format**: No extra whitespace (spaces, newlines) in JSON
+3. **Consistent Serialization**: Use deterministic serialization to prevent variations
+4. **MD5 Consistency**: Any difference will cause ERR_INVALID_MD5 authentication failures
+
+Note: Sorted keys are our METHOD to guarantee requirement #1, not a payware requirement itself.
+
+## 🔗 **Next Steps**
+
+1. Use the deterministic JSON above in your API request
+2. Include the MD5 hash in your JWT header${calculateMD5 ? ` (\`${md5Hash}\`)` : ''}
+3. Send the exact same JSON string in your HTTP request body
+4. Verify with \`payware_authentication_validate_jwt\` tool
+
+---
+**Execution Info:**
+- Tool: payware_utils_format_json_deterministic
+- Keys Processed: ${originalKeys.length}
+- Sorting Required: ${!isAlreadySorted}
+- MD5 Calculated: ${calculateMD5}
+- Executed: ${new Date().toISOString()}
+- Status: ✅ Complete`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **JSON Formatting Failed**
+
+**Error**: ${error.message}
+
+**Common Issues**:
+- Invalid JSON structure
+- Circular references in payload
+- Non-serializable values (functions, undefined, etc.)
+- Different JSON strings used for JWT MD5 vs HTTP body
+
+**Debug Steps for MD5 Errors**:
+1. Verify the SAME string is used for JWT contentMd5 and HTTP body
+2. Check for extra whitespace or formatting differences
+3. Ensure consistent property ordering (use deterministic serialization)
+4. Validate that objects are properly serializable
+5. Test with the consistency validation option
+
+---
+**Execution Info:**
+- Tool: payware_utils_format_json_deterministic
+- Executed: ${new Date().toISOString()}
+- Status: ❌ Error`
+        }]
+      };
+    }
+  }
+};