@payware/mcp-server 1.0.0

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

@@ -0,0 +1,189 @@
+/**
+ * ISV OAuth2 Token Management - Obtain Access Token
+ *
+ * Allows ISVs to request an access token on behalf of a payware registered merchant.
+ * This is the first step in the ISV authorization flow.
+ */
+
+export const obtainTokenTool = {
+  name: 'payware_authorization_oauth2_obtain_token',
+  description: `Obtain an OAuth2 access token for a merchant.
+
+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.
+Store tokens securely using strong encryption.
+
+Endpoint: POST /oauth2/tokens
+Auth: Requires ISV JWT token with aud: "https://payware.eu"`,
+
+  inputSchema: {
+    type: 'object',
+    required: [],
+    properties: {
+      grantType: {
+        type: 'string',
+        enum: ['client_credentials'],
+        default: 'client_credentials',
+        description: 'OAuth2 grant type. Only "client_credentials" is supported.'
+      },
+      clientId: {
+        type: 'string',
+        description: 'The partnerId of the merchant (e.g., "ZJJTFQDQ"). Defaults to PAYWARE_OAUTH_CLIENT_ID env var.'
+      },
+      clientSecret: {
+        type: 'string',
+        description: 'Base64 encoded value of the payware secret of the merchant. Defaults to PAYWARE_OAUTH_CLIENT_SECRET env var.'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler({ grantType = 'client_credentials', clientId, clientSecret, useSandbox = true }) {
+    const axios = (await import('axios')).default;
+    const { createISVJWT } = await import('../utils/auth.js');
+    const { getSandboxUrl, getProductionUrl } = await import('../../config/env.js');
+
+    // Use environment variables as defaults
+    const finalClientId = clientId || process.env.PAYWARE_OAUTH_CLIENT_ID;
+    const finalClientSecret = clientSecret || process.env.PAYWARE_OAUTH_CLIENT_SECRET;
+
+    if (!finalClientId) {
+      throw new Error('Client ID is required. Provide via parameter or set PAYWARE_OAUTH_CLIENT_ID environment variable.');
+    }
+
+    if (!finalClientSecret) {
+      throw new Error('Client Secret is required. Provide via parameter or set PAYWARE_OAUTH_CLIENT_SECRET environment variable.');
+    }
+
+    try {
+      const requestBody = {
+        grantType,
+        clientId: finalClientId,
+        clientSecret: finalClientSecret
+      };
+
+      // Create JWT for OAuth2 request (audience must be https://payware.eu)
+      const jwt = await createISVJWT({
+        requestBody,
+        audience: 'https://payware.eu',
+        isOAuth2Request: true
+      });
+
+      const { createISVAuthHeaders } = await import('../utils/auth.js');
+
+      const apiUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+      const baseUrl = apiUrl.replace('/api', ''); // OAuth2 endpoints don't use /api
+      const headers = createISVAuthHeaders(jwt, true); // true = isOAuth2Request (no Api-Version header)
+
+      const response = await axios.post(`${baseUrl}/oauth2/tokens`, requestBody, {
+        headers
+      });
+
+      const result = response.data;
+
+      return {
+        content: [{
+          type: "text",
+          text: `✅ OAuth2 Token Request Successful
+
+🎯 **NEW ACCESS TOKEN**: ${result.accessToken}
+
+📄 **Response Details:**
+- **Access Token**: ${result.accessToken}
+- **Token Type**: ${result.tokenType}
+- **Status**: ${result.status}
+- **Scope**: ${result.scope}
+- **Expires**: ${result.expiresIn || 'Never (client_credentials tokens do not expire)'}
+
+📋 **Copy this token for next operations:**
+\`${result.accessToken}\`
+
+🔐 **Security Reminder:**
+- Store this token securely with strong encryption
+- Only one token is allowed per merchant
+- 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
+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`
+        }]
+      };
+
+    } catch (error) {
+      let errorMessage = 'OAuth2 token request failed';
+      let errorDetails = {};
+
+      if (error.response) {
+        errorDetails.httpStatus = error.response.status;
+        errorDetails.responseData = error.response.data;
+
+        if (error.response.data?.error) {
+          const errorCode = error.response.data.error;
+          const errorMappings = {
+            'ERR_UNSUPPORTED_GRANT_TYPE': 'Grant type must be "client_credentials"',
+            'ERR_MISSING_CLIENT_ID': 'Client ID (merchant partnerId) is required',
+            'ERR_MISSING_CLIENT_SECRET': 'Client secret (base64 encoded merchant secret) is required',
+            'ERR_CLIENT_NOT_FOUND': 'Merchant not found with provided client ID',
+            'ERR_CLIENT_DISABLED': 'Merchant account is disabled',
+            'ERR_TOKEN_EXISTS': 'Token already exists for this merchant. Only one token per merchant is allowed.'
+          };
+
+          errorMessage = errorMappings[errorCode] || `Error: ${errorCode}`;
+
+          // Special handling for ERR_TOKEN_EXISTS - try to get existing token info
+          if (errorCode === 'ERR_TOKEN_EXISTS') {
+            errorMessage += '\\n\\n🔍 **To find your existing token:**\\n1. Check your secure storage where you saved the previous token\\n2. Or use payware_oauth2_get_token_info if you know the token\\n3. Contact merchant to revoke existing token if you need a new one';
+          }
+        } else {
+          errorMessage = `HTTP ${error.response.status}: ${error.response.statusText}`;
+        }
+      } else if (error.request) {
+        errorMessage = 'Network error - no response received';
+        errorDetails.requestInfo = {
+          url: error.config?.url,
+          method: error.config?.method,
+          headers: error.config?.headers
+        };
+      } else {
+        errorMessage = error.message;
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `❌ OAuth2 Token Request Failed
+
+**Error**: ${errorMessage}
+
+**Request Details:**
+- ISV Partner ID: ${process.env.PAYWARE_PARTNER_ID}
+- Merchant Partner ID: ${finalClientId}
+- Grant Type: ${grantType}
+- Target URL: ${getSandboxUrl().replace('/api', '')}/oauth2/tokens
+
+${Object.keys(errorDetails).length > 0 ? `
+**Error Details:**
+\`\`\`json
+${JSON.stringify(errorDetails, null, 2)}
+\`\`\`
+` : ''}
+
+📋 **Troubleshooting:**
+- 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

@@ -0,0 +1,151 @@
+/**
+ * OAuth2 Token Helper Utility
+ * Helps users manage OAuth2 tokens more easily
+ */
+
+import { obtainTokenTool } from './obtain-token.js';
+import { getTokenInfoTool } from './get-token-info.js';
+
+/**
+ * Helper tool to create or find OAuth2 tokens with clear output
+ */
+export const tokenHelperTool = {
+  name: 'payware_authorization_oauth2_token_helper',
+  description: `OAuth2 Token Helper - Create or manage tokens with clear output.
+
+This tool helps you:
+1. Create new OAuth2 tokens (if none exists)
+2. Guide you on finding existing tokens
+3. Display token information clearly
+
+Use this when you need a token but aren't sure if one exists or what it is.`,
+
+  inputSchema: {
+    type: 'object',
+    required: [],
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['create', 'help'],
+        default: 'create',
+        description: 'Action to perform: create (attempt to create token) or help (show guidance)'
+      },
+      clientId: {
+        type: 'string',
+        description: 'Merchant Partner ID (defaults to PAYWARE_OAUTH_CLIENT_ID env var)'
+      },
+      clientSecret: {
+        type: 'string',
+        description: 'Merchant Secret (defaults to PAYWARE_OAUTH_CLIENT_SECRET env var)'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler({ action = 'create', clientId, clientSecret, useSandbox = true }) {
+    if (action === 'help') {
+      return {
+        content: [{
+          type: 'text',
+          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)
+
+🎯 **To get your token:**
+
+**Option 1: Try creating a token**
+Use: \`payware_oauth2_obtain_token\`
+- If successful: New token will be clearly displayed
+- If error "ERR_TOKEN_EXISTS": A token already exists
+
+**Option 2: Check a known token**
+Use: \`payware_oauth2_get_token_info\` with your saved token
+- Shows current status (PENDING/GRANTED/REVOKED)
+
+**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
+
+🔐 **Security:**
+- Always store tokens securely
+- Keep a backup copy in secure location
+- Never share tokens or commit to code repositories`
+        }]
+      };
+    }
+
+    // Try to create a token
+    const result = await obtainTokenTool.handler({ clientId, clientSecret, useSandbox });
+
+    // Check if the result indicates an ERR_TOKEN_EXISTS error
+    if (result.content?.[0]?.text?.includes('ERR_TOKEN_EXISTS')) {
+      return {
+        content: [{
+          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).
+
+📋 **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 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
+
+💡 **Tip:** Always keep a secure backup of your OAuth2 tokens!
+
+📋 **For immediate help:**
+Run this tool with action='help' for more detailed guidance.`
+        }]
+      };
+    }
+
+    // If successful, extract and highlight the token
+    const tokenMatch = result.content?.[0]?.text?.match(/NEW ACCESS TOKEN\*\*: ([A-Za-z0-9]+)/);
+    const token = tokenMatch ? tokenMatch[1] : null;
+
+    if (token) {
+      return {
+        content: [{
+          type: 'text',
+          text: `${result.content[0].text}
+
+🚨 **IMPORTANT: SAVE THIS TOKEN NOW!**
+
+📋 **Your OAuth2 Token:**
+\`\`\`
+${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}\`
+3. Wait for merchant approval (status will change to GRANTED)
+4. Use token in API requests once GRANTED`
+        }]
+      };
+    }
+
+    // Return original result if we can't extract token but no error occurred
+    return result;
+  }
+};
+
+export default tokenHelperTool;