@payware/mcp-server 1.0.0

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

@@ -0,0 +1,735 @@
+import jwt from 'jsonwebtoken';
+import crypto from 'crypto';
+import { normalizePrivateKey, getKeyInfo } from '../utils/key-utils.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { createDeterministicJSON } from '../utils/json-serializer.js';
+
+/**
+ * Generate MD5 hash for JWT contentMd5 header
+ *
+ * PAYWARE REQUIREMENT: The MD5 hash must be calculated from the EXACT same
+ * compact JSON string that will be sent as the HTTP request body.
+ *
+ * CRITICAL: Any difference in whitespace, property order, or formatting
+ * between the string used for MD5 and the HTTP body will cause authentication
+ * failures with ERR_INVALID_MD5 errors.
+ *
+ * @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;
+
+  // CRITICAL: Use deterministic JSON serialization with sorted keys
+  // This ensures consistent MD5 hashes regardless of property order
+  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 MD5 and HTTP request body
+ *
+ * PAYWARE REQUIREMENT: The same compact JSON string must be used for:
+ * 1. JWT contentMd5 calculation (passed to generateContentMd5)
+ * 2. HTTP request body (sent to payware API)
+ *
+ * This function guarantees consistency by using deterministic serialization.
+ * Any mismatch between these two uses will result in authentication failure.
+ *
+ * @param {Object} payload - Request payload object
+ * @returns {string} Compact JSON string for both MD5 and HTTP body
+ */
+export function serializePayload(payload) {
+  if (!payload) return null;
+  if (typeof payload === 'string') return payload;
+
+  // Use deterministic JSON serialization with sorted keys
+  // This ensures consistent serialization regardless of property order
+  return createDeterministicJSON(payload);
+}
+
+/**
+ * Create JWT token for payware API authentication according to documentation
+ * @param {string} partnerId - Partner ID from payware
+ * @param {string} privateKey - RSA private key in PEM format
+ * @param {Object} requestBody - Request body (for POST/PUT/PATCH requests)
+ * @returns {Object} Object containing JWT token and metadata
+ */
+export function createJWTToken(partnerId, privateKey, requestBody = null) {
+  const now = Math.floor(Date.now() / 1000);
+  
+  // Normalize the private key to handle flexible formats
+  const normalizedKey = normalizePrivateKey(privateKey);
+  
+  // JWT Header (as per documentation)
+  const header = {
+    alg: 'RS256',
+    typ: 'JWT'
+  };
+  
+  // Add contentMd5 to header if request body exists (for POST/PUT/PATCH)
+  // CRITICAL: The requestBody here must be the EXACT same string that will
+  // be sent as the HTTP request body, otherwise MD5 will not match
+  if (requestBody) {
+    header.contentMd5 = generateContentMd5(requestBody);
+  }
+  
+  // JWT Payload (as per documentation)
+  const payload = {
+    iss: partnerId,
+    aud: 'https://payware.eu',  // Required by documentation
+    iat: now
+  };
+  
+  const token = jwt.sign(payload, normalizedKey, { 
+    algorithm: 'RS256',
+    header: header
+  });
+  
+  return {
+    token,
+    partnerId,
+    audience: 'https://payware.eu',
+    issuedAt: new Date(now * 1000).toISOString(),
+    contentMd5: header.contentMd5 || null,
+    hasBody: !!requestBody
+  };
+}
+
+/**
+ * Create request signature for payware API (legacy - may not be needed with proper JWT)
+ * @param {string} method - HTTP method (GET, POST, etc.)
+ * @param {string} path - API path
+ * @param {Object} body - Request body (for POST requests)
+ * @param {string} privateKey - RSA private key in PEM format
+ * @returns {string} Base64 encoded signature
+ */
+export function createRequestSignature(method, path, body, privateKey) {
+  const bodyString = body ? JSON.stringify(body) : '';
+  const stringToSign = `${method.toUpperCase()}${path}${bodyString}`;
+  
+  const sign = crypto.createSign('RSA-SHA256');
+  sign.update(stringToSign);
+  sign.end();
+  
+  const signature = sign.sign(privateKey, 'base64');
+  return signature;
+}
+
+/**
+ * Validate and debug JWT token implementation
+ */
+export const validateJWTTokenTool = {
+  name: "payware_authentication_validate_jwt",
+  description: "Validate and debug JWT token structure, decode payload/headers, verify MD5 calculation, and check RS256 signature format for payware API compliance",
+  inputSchema: {
+    type: "object",
+    properties: {
+      jwtToken: {
+        type: "string",
+        description: "JWT token to validate and debug"
+      },
+      expectedPayload: {
+        type: "object",
+        description: "Expected request body (optional - for MD5 validation)"
+      }
+    },
+    required: ["jwtToken"],
+    additionalProperties: false
+  },
+
+  async handler(args) {
+    const { jwtToken, expectedPayload } = args;
+
+    if (!jwtToken) {
+      throw new Error("JWT token is required");
+    }
+
+    try {
+      // Parse JWT token without verification first
+      const decoded = jwt.decode(jwtToken, { complete: true });
+
+      if (!decoded) {
+        throw new Error("Invalid JWT token format");
+      }
+
+      const { header, payload } = decoded;
+
+      // Validation results
+      const validation = {
+        structure: true,
+        algorithm: header.alg === 'RS256',
+        type: header.typ === 'JWT',
+        audience: payload.aud === 'https://payware.eu',
+        issuer: !!payload.iss,
+        issuedAt: !!payload.iat,
+        contentMd5: header.contentMd5 ? true : false
+      };
+
+      // MD5 validation if expected payload provided
+      let md5Validation = null;
+      if (expectedPayload && header.contentMd5) {
+        const calculatedMd5 = generateContentMd5(expectedPayload);
+        md5Validation = {
+          provided: header.contentMd5,
+          calculated: calculatedMd5,
+          matches: header.contentMd5 === calculatedMd5,
+          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 (!validation.issuer) issues.push("Missing issuer (iss) claim");
+      if (!validation.issuedAt) issues.push("Missing issued at (iat) claim");
+      if (md5Validation && !md5Validation.matches) {
+        issues.push("MD5 hash mismatch - ensure deterministic JSON serialization with sorted keys");
+      }
+
+      const overallValid = Object.values(validation).every(v => v) && (!md5Validation || md5Validation.matches);
+
+      return {
+        content: [{
+          type: "text",
+          text: `🔍 **JWT Token Validation Report**
+
+${overallValid ? '✅ **VALID JWT TOKEN**' : '❌ **INVALID JWT TOKEN**'}
+
+## JWT Structure Analysis
+
+**Header:**
+\`\`\`json
+${JSON.stringify(header, null, 2)}
+\`\`\`
+
+**Payload:**
+\`\`\`json
+${JSON.stringify(payload, null, 2)}
+\`\`\`
+
+## Validation Results
+
+${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.issuer ? '✅' : '❌'} **Issuer**: ${payload.iss || 'Missing'}
+${validation.issuedAt ? '✅' : '❌'} **Issued At**: ${payload.iat ? new Date(payload.iat * 1000).toISOString() : 'Missing'}
+${validation.contentMd5 ? '✅' : 'ℹ️'} **Content MD5**: ${header.contentMd5 || 'Not present (OK for GET requests)'}
+
+${md5Validation ? `## MD5 Hash Validation
+
+${md5Validation.matches ? '✅' : '❌'} **MD5 Match**: ${md5Validation.matches ? 'Correct' : 'Mismatch detected'}
+**Provided**: \`${md5Validation.provided}\`
+**Calculated**: \`${md5Validation.calculated}\`
+
+**Deterministic JSON Used**:
+\`\`\`json
+${md5Validation.deterministicJson}
+\`\`\`
+
+${!md5Validation.matches ? `
+⚠️ **MD5 Mismatch Debugging**:
+
+PAYWARE REQUIREMENT: The EXACT same compact JSON string must be used for both JWT contentMd5 and HTTP body.
+
+**Common Causes**:
+1. Different JSON strings used for JWT MD5 vs HTTP body
+2. Extra whitespace or formatting differences
+3. Property order variations between serializations
+
+**Solution**: Use deterministic JSON serialization to guarantee consistency
+
+**Correct Implementation Pattern**:
+\`\`\`python
+# Use deterministic JSON serialization
+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)
+\`\`\`
+` : ''}
+` : ''}
+
+${issues.length > 0 ? `## ⚠️ Issues Found
+
+${issues.map(issue => `- ${issue}`).join('\n')}
+
+## Recommendations
+
+${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' : ''}
+${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('MD5 hash mismatch')) ? '- Use deterministic JSON serialization with sorted keys\n- Ensure same JSON string for MD5 and HTTP body\n' : ''}
+` : '## ✅ No Issues Found\n\nYour JWT token is properly formatted for payware API usage.'}
+
+## Technical Details
+
+**Token Length**: ${jwtToken.length} characters
+**Validation Timestamp**: ${new Date().toISOString()}
+**payware API Compliance**: ${overallValid ? 'PASS' : 'FAIL'}
+
+---
+**Execution Info:**
+- Tool: payware_authentication_validate_jwt
+- Executed: ${new Date().toISOString()}
+- Status: ${overallValid ? '✅ Valid' : '❌ Invalid'}`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **JWT Validation Failed**
+
+**Error**: ${error.message}
+
+## Common JWT Issues
+
+1. **Invalid Format**: JWT should have 3 parts separated by dots (header.payload.signature)
+2. **Invalid Base64**: JWT parts must be valid Base64 encoded
+3. **Malformed JSON**: Header and payload must be valid JSON
+4. **Missing Components**: Ensure all required claims are present
+
+## Debug Steps
+
+1. Check that your JWT has exactly 2 dots separating 3 parts
+2. Verify each part is valid Base64
+3. Decode header and payload manually to check JSON structure
+4. Ensure all required claims (iss, aud, iat) are present
+
+**Token Provided**: ${jwtToken.substring(0, 50)}...
+
+---
+**Execution Info:**
+- Tool: payware_authentication_validate_jwt
+- Executed: ${new Date().toISOString()}
+- Status: ❌ Error`
+        }]
+      };
+    }
+  }
+};
+
+/**
+ * Test JWT token creation with step-by-step breakdown
+ */
+export const testJWTTokenTool = {
+  name: "payware_authentication_test_jwt",
+  description: "Test JWT token creation process with detailed step-by-step breakdown, showing deterministic JSON serialization, MD5 calculation, and final JWT structure",
+  inputSchema: {
+    type: "object",
+    properties: {
+      partnerId: {
+        type: "string",
+        description: "Partner ID for JWT creation (defaults to environment)"
+      },
+      requestPayload: {
+        type: "object",
+        description: "Sample request payload to demonstrate MD5 calculation"
+      },
+      showPrivateKey: {
+        type: "boolean",
+        description: "Whether to show private key details (for debugging)",
+        default: false
+      }
+    },
+    additionalProperties: false
+  },
+
+  async handler(args) {
+    const {
+      partnerId = getPartnerIdSafe(),
+      requestPayload = { amount: "25.50", currency: "EUR", reasonL1: "Test payment" },
+      showPrivateKey = false
+    } = args;
+
+    if (!partnerId) {
+      throw new Error("Partner ID is required. Set PAYWARE_PARTNER_ID environment variable or provide as parameter.");
+    }
+
+    const privateKey = getPrivateKeySafe();
+    if (!privateKey) {
+      throw new Error("Private key is required. Set PAYWARE_SANDBOX_PRIVATE_KEY_PATH environment variable.");
+    }
+
+    try {
+      const steps = [];
+
+      // Step 1: JSON Serialization
+      const originalJson = JSON.stringify(requestPayload);
+      const deterministicJson = createDeterministicJSON(requestPayload);
+      const sortedKeys = Object.keys(requestPayload).sort();
+
+      steps.push(`**Step 1: JSON Serialization**
+Input payload:
+\`\`\`json
+${JSON.stringify(requestPayload, null, 2)}
+\`\`\`
+
+❌ **Standard JSON.stringify()** (property order varies):
+\`\`\`json
+${originalJson}
+\`\`\`
+
+✅ **Deterministic JSON** (sorted keys):
+\`\`\`json
+${deterministicJson}
+\`\`\`
+
+**Key Sorting**: [${sortedKeys.join(', ')}]`);
+
+      // Step 2: MD5 Calculation
+      const md5Hash = generateContentMd5(requestPayload);
+
+      steps.push(`**Step 2: MD5 Hash Calculation**
+Using deterministic JSON string:
+\`\`\`
+${deterministicJson}
+\`\`\`
+
+MD5 hash (Base64): \`${md5Hash}\`
+
+**Process**:
+1. Create MD5 hash from UTF-8 bytes of deterministic JSON
+2. Encode hash as Base64
+3. Include in JWT header as \`contentMd5\``);
+
+      // Step 3: JWT Header Construction
+      const jwtHeader = {
+        alg: 'RS256',
+        typ: 'JWT',
+        contentMd5: md5Hash
+      };
+
+      steps.push(`**Step 3: JWT Header Construction**
+\`\`\`json
+${JSON.stringify(jwtHeader, null, 2)}
+\`\`\`
+
+**Requirements**:
+- Algorithm: RS256 (RSA with SHA-256)
+- Type: JWT
+- Content MD5: ${md5Hash}`);
+
+      // Step 4: JWT Payload Construction
+      const now = Math.floor(Date.now() / 1000);
+      const jwtPayload = {
+        iss: partnerId,
+        aud: 'https://payware.eu',
+        iat: now
+      };
+
+      steps.push(`**Step 4: JWT Payload Construction**
+\`\`\`json
+${JSON.stringify(jwtPayload, null, 2)}
+\`\`\`
+
+**Requirements**:
+- Issuer (iss): Your partner ID
+- Audience (aud): **MUST be https://payware.eu** (not just "payware")
+- Issued At (iat): Unix timestamp (${new Date(now * 1000).toISOString()})`);
+
+      // Step 5: JWT Token Creation
+      const finalToken = createJWTToken(partnerId, privateKey, requestPayload);
+
+      steps.push(`**Step 5: JWT Token Creation**
+Final JWT token:
+\`\`\`
+${finalToken.token}
+\`\`\`
+
+**Token Components**:
+- Header (Base64): \`${finalToken.token.split('.')[0]}\`
+- Payload (Base64): \`${finalToken.token.split('.')[1]}\`
+- Signature (Base64): \`${finalToken.token.split('.')[2].substring(0, 20)}...\`
+
+**Length**: ${finalToken.token.length} characters`);
+
+      // Step 6: Private Key Information
+      const keyInfo = getKeyInfo(privateKey);
+      const keyDetails = showPrivateKey ?
+        `**Private Key Details**:
+- Format: ${keyInfo.format}
+- Has Headers: ${keyInfo.hasHeaders}
+- Length: ${keyInfo.length} characters
+- Type: ${keyInfo.isPrivate ? 'Private' : 'Unknown'}` :
+        `**Private Key**: Available (${keyInfo.format}, ${keyInfo.length} chars)
+*Use \`showPrivateKey: true\` for more details*`;
+
+      steps.push(`**Step 6: Signature Creation**
+${keyDetails}
+
+**Signature Process**:
+1. Combine Base64(header) + "." + Base64(payload)
+2. Sign with RSA private key using SHA-256
+3. Encode signature as Base64
+4. Final JWT: header.payload.signature`);
+
+      return {
+        content: [{
+          type: "text",
+          text: `🧪 **JWT Token Creation Test - Step by Step**
+
+${steps.join('\n\n---\n\n')}
+
+## ✅ **Complete JWT Ready for API Use**
+
+**Headers for API Request**:
+\`\`\`
+Authorization: Bearer ${finalToken.token}
+Content-Type: application/json
+Api-Version: 1
+\`\`\`
+
+**HTTP Request Body** (must match deterministic JSON):
+\`\`\`json
+${deterministicJson}
+\`\`\`
+
+## 🔑 **Key Insights**
+
+1. **Deterministic JSON is Critical**: Property order MUST be sorted
+2. **MD5 Consistency**: Same JSON string for both MD5 and HTTP body
+3. **Audience Requirement**: Must be "https://payware.eu" (include https://)
+4. **RS256 Algorithm**: RSA with SHA-256 signature
+5. **Content MD5 in Header**: Not in payload, but in JWT header
+
+## 🐛 **Common Mistakes to Avoid**
+
+❌ Using \`JSON.stringify()\` without sorted keys
+❌ Different JSON for MD5 vs HTTP request
+❌ Setting audience to "payware" instead of "https://payware.eu"
+❌ Putting contentMd5 in payload instead of header
+❌ Using wrong algorithm (HS256 instead of RS256)
+
+---
+**Execution Info:**
+- Tool: payware_authentication_test_jwt
+- Partner ID: ${partnerId}
+- Executed: ${new Date().toISOString()}
+- Status: ✅ Complete`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **JWT Testing Failed**
+
+**Error**: ${error.message}
+
+**Common Issues**:
+- Missing environment variables (PAYWARE_PARTNER_ID, PAYWARE_SANDBOX_PRIVATE_KEY_PATH)
+- Invalid private key format
+- Permission issues reading private key file
+
+**Debug Steps**:
+1. Check that environment variables are set
+2. Verify private key file exists and is readable
+3. Ensure private key is in proper PEM format
+
+---
+**Execution Info:**
+- Tool: payware_authentication_test_jwt
+- Executed: ${new Date().toISOString()}
+- Status: ❌ Error`
+        }]
+      };
+    }
+  }
+};
+
+/**
+ * Create JWT token tool implementation
+ */
+export const createJWTTokenTool = {
+  name: "payware_authentication_create_jwt_token",
+  description: "Create JWT token for payware API authentication according to official documentation",
+  inputSchema: {
+    type: "object",
+    properties: {
+      partnerId: {
+        type: "string",
+        description: "Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default."
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key - accepts PEM format with/without headers or raw base64 content. Uses environment-specific private key as default."
+      },
+      requestBody: {
+        type: "object",
+        description: "Request body (for POST/PUT/PATCH requests that need contentMd5)"
+      }
+    },
+    additionalProperties: false
+  },
+  
+  async handler(args) {
+    const {
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe(),
+      requestBody
+    } = args;
+
+    if (!partnerId) {
+      throw new Error("Partner ID is required. Provide via 'partnerId' parameter or set PAYWARE_PARTNER_ID environment variable.");
+    }
+
+    if (!privateKey) {
+      throw new Error("Private key is required. Provide via 'privateKey' parameter or set environment-specific private key variable.");
+    }
+    
+    // Get key info for validation and user feedback
+    const keyInfo = getKeyInfo(privateKey);
+    
+    try {
+      const tokenData = createJWTToken(partnerId, privateKey, requestBody);
+      
+      // Add key format information to the response
+      const keyFormatInfo = keyInfo.hasHeaders 
+        ? `✅ Standard PEM format (${keyInfo.format})`
+        : `🔧 Normalized from base64 content to PEM format`;
+      
+      const originalResponse = tokenData;
+    
+    return {
+      content: [{
+        type: "text",
+        text: `🔑 **JWT Token Created Successfully (payware Specification)**
+
+**🔧 Key Format:** ${keyFormatInfo}
+
+**Token:**
+\`\`\`
+${tokenData.token}
+\`\`\`
+
+**Token Details:**
+- Partner ID (iss): ${tokenData.partnerId}
+- Audience (aud): ${tokenData.audience}
+- Issued At (iat): ${tokenData.issuedAt}
+- Algorithm: RS256
+- Type: JWT
+${tokenData.contentMd5 ? `- Content MD5: ${tokenData.contentMd5}` : '- Content MD5: Not included (no request body)'}
+
+**JWT Structure (Decoded):**
+**Header:**
+\`\`\`json
+{
+  "alg": "RS256",
+  "typ": "JWT"${tokenData.contentMd5 ? `,\n  "contentMd5": "${tokenData.contentMd5}"` : ''}
+}
+\`\`\`
+
+**Payload:**
+\`\`\`json
+{
+  "iss": "${tokenData.partnerId}",
+  "aud": "https://payware.eu",
+  "iat": ${Math.floor(Date.parse(tokenData.issuedAt) / 1000)}
+}
+\`\`\`
+
+**Usage:**
+Add these headers to your API requests:
+\`\`\`
+Authorization: Bearer ${tokenData.token}
+Api-Version: 1
+Content-Type: application/json
+\`\`\`
+
+**✅ Complies with payware Documentation:**
+- ✅ Algorithm: RS256
+- ✅ Type: JWT  
+- ✅ Issuer: Your Partner ID
+- ✅ Audience: https://payware.eu
+- ✅ Issued At: Unix timestamp
+${tokenData.contentMd5 ? '- ✅ Content MD5: Included for request body' : '- ℹ️ Content MD5: Not needed for GET requests'}
+
+**📝 Private Key Formats Supported:**
+- ✅ Full PEM format with headers/footers
+- ✅ Base64 content only (headers added automatically)
+- ✅ Mixed formats (normalized automatically)
+
+## ⚠️ **CRITICAL AUTHENTICATION REQUIREMENTS**
+
+### JSON Body Consistency Rule
+${tokenData.contentMd5 ? `**Your contentMd5 (${tokenData.contentMd5}) MUST match the exact bytes sent in HTTP request.**
+
+❌ **Common Error Causing ERR_INVALID_MD5:**
+\`\`\`python
+# Wrong - different serialization formats!
+jwt_token = create_jwt(json.dumps(payload))  # One format
+requests.post(url, json=payload)            # Different format!
+\`\`\`
+
+✅ **Correct Implementation:**
+\`\`\`python
+# Same serialization for both MD5 and HTTP body
+json_body = json.dumps(payload, separators=(',', ':'))  # Compact format
+jwt_token = create_jwt(json_body)
+requests.post(url, data=json_body, headers=headers)
+\`\`\`
+` : '**No request body - No MD5 consistency concerns for GET requests.**'}
+
+### Troubleshooting Authentication Errors
+
+**ERR_INVALID_MD5** - MD5 hash mismatch:
+- Cause: JWT contentMd5 doesn't match HTTP request body bytes
+- Fix: Use identical JSON serialization for both MD5 calculation and HTTP request
+- Common issue: \`requests.post(json=data)\` vs \`requests.post(data=json_string)\`
+
+**ERR_INVALID_SIGNATURE** - JWT signature validation failed:
+- Cause: Private key mismatch or malformed JWT
+- Fix: Ensure your private key matches the public key registered with payware
+- Check: JWT structure, algorithm (RS256), audience (https://payware.eu)
+
+### Language-Specific Best Practices
+
+**Python (requests library):**
+\`\`\`python
+import json
+import requests
+
+# CRITICAL: Use same serialization for both
+json_body = json.dumps(payload, separators=(',', ':'))
+jwt_token = create_jwt_token(json_body)
+response = requests.post(url, data=json_body, headers={'Authorization': f'Bearer {jwt_token}'})
+\`\`\`
+
+**Node.js (axios library):**
+\`\`\`javascript
+const jsonBody = JSON.stringify(payload);
+const jwtToken = createJWTToken(jsonBody);
+const response = await axios.post(url, jsonBody, {headers: {'Authorization': \`Bearer \${jwtToken}\`}});
+\`\`\`
+
+**⚠️ Security Notes:**
+- Token is valid for sandbox environment only
+- Do not share or log this token
+- Generate new token for each request with different body
+- Ensure your public key is registered with payware
+- **Critical:** Always use matching JSON serialization for MD5 and HTTP body`
+      }]
+    };
+    } catch (error) {
+      // Provide helpful error message based on the error type
+      let errorMessage = `Failed to create JWT token: ${error.message}`;
+      
+      if (error.message.includes('key')) {
+        errorMessage += `\n\n**Key Format Help:**\nYou can provide the private key in any of these formats:\n- Full PEM format with -----BEGIN/END----- headers\n- Just the base64 content (headers will be added automatically)\n- Current key info: ${keyInfo.format}`;
+      }
+      
+      throw new Error(errorMessage);
+    }
+  }
+};