ebay-mcp 1.4.3

package/build/auth/oauth.js

@@ -0,0 +1,383 @@
+import axios from 'axios';
+import { getBaseUrl, getDefaultScopes } from '../config/environment.js';
+import { LocaleEnum } from '../types/ebay-enums.js';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Update .env file with new token values
+ */
+function updateEnvFile(updates) {
+    try {
+        const envPath = join(process.cwd(), '.env');
+        let envContent = readFileSync(envPath, 'utf-8');
+        // Update each key-value pair
+        for (const [key, value] of Object.entries(updates)) {
+            // Match the key with or without value, handling comments
+            const regex = new RegExp(`^(#\\s*)?${key}=.*$`, 'gm');
+            const newLine = `${key}=${value}`;
+            if (regex.test(envContent)) {
+                // Update existing key (uncomment if needed)
+                envContent = envContent.replace(regex, newLine);
+            }
+            else {
+                // Add new key at the end
+                envContent += `\n${newLine}`;
+            }
+        }
+        writeFileSync(envPath, envContent, 'utf-8');
+        console.log('✅ Updated .env file with new tokens');
+    }
+    catch (error) {
+        console.error('⚠️  Failed to update .env file:', error instanceof Error ? error.message : error);
+        console.error('   Please manually update your .env file with the new tokens');
+    }
+}
+/**
+ * Manages eBay OAuth 2.0 authentication
+ * Loads tokens exclusively from environment variables (.env file)
+ * Supports both client credentials (app tokens) and user access tokens with refresh
+ */
+export class EbayOAuthClient {
+    config;
+    appAccessToken = null;
+    appAccessTokenExpiry = 0;
+    userTokens = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Initialize user tokens from environment variables only
+     * If EBAY_USER_REFRESH_TOKEN exists, automatically refresh to get a valid access token
+     */
+    async initialize() {
+        const envRefreshToken = process.env.EBAY_USER_REFRESH_TOKEN;
+        const envAccessToken = process.env.EBAY_USER_ACCESS_TOKEN;
+        const envAppToken = process.env.EBAY_APP_ACCESS_TOKEN ?? '';
+        const locale = this.config?.locale || LocaleEnum.en_US;
+        if (envRefreshToken) {
+            console.log('📝 Loading refresh token, access token and app to env file...');
+            // Create token object with just the refresh token from environment
+            // Note: We don't set scopes here - eBay will return the scopes when we refresh
+            const now = Date.now();
+            this.userTokens = {
+                clientId: this.config.clientId,
+                clientSecret: this.config.clientSecret,
+                userAccessToken: envAccessToken || '', // Can be empty, will be filled by refresh
+                userRefreshToken: envRefreshToken,
+                redirectUri: this.config.redirectUri,
+                envAppToken,
+                tokenType: 'Bearer',
+                locale,
+                userAccessTokenExpiry: now + 7200 * 1000, // Default 2 hours
+                userRefreshTokenExpiry: now + 18 * 30 * 24 * 60 * 60 * 1000, // Default 18 months
+                // scope is not set - will be populated by the refresh response
+            };
+            // Immediately refresh to get a valid access token and scopes
+            console.log('🔄 Refreshing access token using refresh token from .env...');
+            try {
+                await this.refreshUserToken();
+                console.log('✅ Access token refreshed successfully from .env configuration.');
+                await this.getOrRefreshAppAccessToken();
+            }
+            catch (error) {
+                console.error('❌ Failed to refresh access token:', error instanceof Error ? error.message : error);
+                console.error('   The EBAY_USER_REFRESH_TOKEN in .env may be invalid or expired.');
+                console.error('   Please update EBAY_USER_REFRESH_TOKEN or use ebay_set_user_tokens_with_expiry tool.');
+                // Clear invalid tokens
+                this.userTokens = null;
+            }
+        }
+    }
+    /**
+     * Check if user tokens are available
+     */
+    hasUserTokens() {
+        return this.userTokens !== null;
+    }
+    /**
+     * Check if user access token is expired
+     */
+    isUserAccessTokenExpired(tokens) {
+        return tokens.userAccessTokenExpiry ? Date.now() >= tokens.userAccessTokenExpiry : true;
+    }
+    /**
+     * Check if user refresh token is expired
+     */
+    isUserRefreshTokenExpired(tokens) {
+        return tokens.userRefreshTokenExpiry ? Date.now() >= tokens.userRefreshTokenExpiry : true;
+    }
+    /**
+     * Get a valid access token, with priority order:
+     * 1. User access token (if available and valid, or refreshable)
+     * 2. App access token from client credentials (fallback)
+     */
+    async getAccessToken() {
+        // Try to use user token first
+        if (this.userTokens) {
+            // Check if access token is still valid
+            if (!this.isUserAccessTokenExpired(this.userTokens)) {
+                return this.userTokens.userAccessToken;
+            }
+            // Try to refresh if refresh token is valid
+            if (!this.isUserRefreshTokenExpired(this.userTokens)) {
+                try {
+                    await this.refreshUserToken();
+                    return this.userTokens.userAccessToken;
+                }
+                catch (error) {
+                    console.error('Failed to refresh user token, falling back to app access token:', error);
+                    // Clear invalid tokens
+                    this.userTokens = null;
+                }
+            }
+            else {
+                // Refresh token expired
+                console.error('User refresh token expired. User needs to re-authorize.');
+                this.userTokens = null;
+                throw new Error('User authorization expired. Please update EBAY_USER_REFRESH_TOKEN in .env with a new refresh token.');
+            }
+        }
+        // Fallback to app access token (client credentials)
+        if (this.appAccessToken && Date.now() < this.appAccessTokenExpiry) {
+            return this.appAccessToken;
+        }
+        await this.getOrRefreshAppAccessToken();
+        return this.appAccessToken;
+    }
+    /**
+     * Set user access token and refresh token
+     * Stores tokens in memory and updates .env file for persistence
+     */
+    setUserTokens(accessToken, refreshToken, accessTokenExpiry, refreshTokenExpiry) {
+        // Store tokens in memory with default expiry
+        // Access tokens typically expire in 2 hours (7200 seconds)
+        // Refresh tokens typically expire in 18 months
+        const now = Date.now();
+        this.userTokens = {
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            redirectUri: this.config.redirectUri,
+            userAccessToken: accessToken,
+            userRefreshToken: refreshToken,
+            tokenType: 'Bearer',
+            userAccessTokenExpiry: accessTokenExpiry ?? (now + 7200 * 1000), // Default 2 hours
+            userRefreshTokenExpiry: refreshTokenExpiry ?? (now + 18 * 30 * 24 * 60 * 60 * 1000), // Default 18 months
+        };
+        // Update .env file with new tokens
+        updateEnvFile({
+            EBAY_USER_ACCESS_TOKEN: accessToken,
+            EBAY_USER_REFRESH_TOKEN: refreshToken,
+        });
+    }
+    /**
+     * Get or refresh the app access token using the client credentials flow.
+     * This method ensures that a valid app access token is always available.
+     * Rate limit: 1,000 requests/day
+     */
+    async getOrRefreshAppAccessToken() {
+        // Return cached token if still valid
+        if (this.appAccessToken) {
+            return this.appAccessToken;
+        }
+        const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        // Client credentials flow only supports basic scope
+        // User authorization flows can request additional scopes
+        const scopeParam = 'https://api.ebay.com/oauth/api_scope';
+        try {
+            const response = await axios.post(authUrl, new URLSearchParams({
+                grant_type: 'client_credentials',
+                scope: scopeParam,
+            }).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Authorization: `Basic ${credentials}`,
+                },
+            });
+            this.appAccessToken = response.data.access_token;
+            // Set expiry with 60 second buffer
+            this.appAccessTokenExpiry = Date.now() + (response.data.expires_in - 60) * 1000;
+            // Update .env file with app access token
+            updateEnvFile({
+                EBAY_APP_ACCESS_TOKEN: this.appAccessToken,
+            });
+            return this.appAccessToken;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                throw new Error(`Failed to get app access token: ${error.response?.data?.error_description || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Exchange authorization code for user access token
+     * Note: After receiving tokens, manually add EBAY_USER_REFRESH_TOKEN to .env file
+     */
+    async exchangeCodeForToken(code) {
+        if (!this.config.redirectUri) {
+            throw new Error('Redirect URI is required for authorization code exchange');
+        }
+        const tokenUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        try {
+            const response = await axios.post(tokenUrl, new URLSearchParams({
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.config.redirectUri,
+            }).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Authorization: `Basic ${credentials}`,
+                },
+            });
+            const tokenData = response.data;
+            // Store the user tokens in memory
+            const now = Date.now();
+            this.userTokens = {
+                clientId: this.config.clientId,
+                clientSecret: this.config.clientSecret,
+                redirectUri: this.config.redirectUri,
+                userAccessToken: tokenData.access_token,
+                userRefreshToken: tokenData.refresh_token,
+                tokenType: tokenData.token_type,
+                userAccessTokenExpiry: now + tokenData.expires_in * 1000,
+                userRefreshTokenExpiry: now + tokenData.refresh_token_expires_in * 1000,
+                scope: tokenData.scope,
+            };
+            // Inform user to save refresh token to .env
+            console.log('\nToken exchange successful!');
+            console.log('To persist your authentication, add this to your .env file:');
+            console.log(`EBAY_USER_REFRESH_TOKEN="${tokenData.refresh_token}"\n`);
+            return tokenData;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                throw new Error(`Failed to exchange code for token: ${error.response?.data?.error_description || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Refresh user access token using refresh token from .env
+     * This method is public and can be called by LLMs when encountering authentication errors
+     */
+    async refreshUserToken() {
+        if (!this.userTokens) {
+            throw new Error('No user tokens available to refresh');
+        }
+        // Use the token endpoint, not the authorization endpoint
+        const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        try {
+            // Prepare refresh token request parameters
+            // Note: We do NOT include scopes in refresh requests as eBay will return
+            // the scopes that were originally granted to the refresh token
+            const params = {
+                grant_type: 'refresh_token',
+                refresh_token: this.userTokens.userRefreshToken,
+            };
+            const response = await axios.post(authUrl, new URLSearchParams(params).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Authorization: `Basic ${credentials}`,
+                },
+            });
+            const tokenData = response.data;
+            // Update tokens in memory
+            const now = Date.now();
+            this.userTokens = {
+                clientId: this.config.clientId,
+                clientSecret: this.config.clientSecret,
+                redirectUri: this.config.redirectUri,
+                userAccessToken: tokenData.access_token,
+                userRefreshToken: tokenData.refresh_token || this.userTokens.userRefreshToken, // Use new refresh token if provided
+                tokenType: tokenData.token_type,
+                userAccessTokenExpiry: now + tokenData.expires_in * 1000,
+                userRefreshTokenExpiry: tokenData.refresh_token_expires_in
+                    ? now + tokenData.refresh_token_expires_in * 1000
+                    : this.userTokens.userRefreshTokenExpiry, // Keep existing expiry if not provided
+                // eBay may not return scope in refresh response - preserve existing scope if not returned
+                scope: tokenData.scope || this.userTokens.scope,
+            };
+            // Update .env file with new tokens
+            const envUpdates = {
+                EBAY_USER_ACCESS_TOKEN: tokenData.access_token,
+            };
+            // If eBay provided a new refresh token, update it too
+            if (tokenData.refresh_token && tokenData.refresh_token !== process.env.EBAY_USER_REFRESH_TOKEN) {
+                envUpdates.EBAY_USER_REFRESH_TOKEN = tokenData.refresh_token;
+                console.log('\n🔄 eBay issued a new refresh token - updating .env file');
+            }
+            // Write updates to .env file
+            updateEnvFile(envUpdates);
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                throw new Error(`Failed to refresh token: ${error.response?.data?.error_description || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if currently authenticated (either user or app credentials)
+     */
+    isAuthenticated() {
+        if (this.userTokens && !this.isUserAccessTokenExpired(this.userTokens)) {
+            return true;
+        }
+        return this.appAccessToken !== null && Date.now() < this.appAccessTokenExpiry;
+    }
+    /**
+     * Clear all authentication tokens from memory
+     * Note: To persist this change, remove EBAY_USER_REFRESH_TOKEN from .env
+     */
+    clearAllTokens() {
+        this.appAccessToken = null;
+        this.appAccessTokenExpiry = 0;
+        this.userTokens = null;
+    }
+    /**
+     * Get current token info for debugging
+     */
+    getTokenInfo() {
+        const info = {
+            hasUserToken: this.userTokens !== null && !this.isUserAccessTokenExpired(this.userTokens),
+            hasAppAccessToken: this.appAccessToken !== null && Date.now() < this.appAccessTokenExpiry,
+        };
+        // Add scope comparison info if user tokens are available
+        if (this.userTokens?.scope) {
+            const tokenScopes = this.userTokens.scope.split(' ');
+            const environmentScopes = getDefaultScopes(this.config.environment);
+            const tokenScopeSet = new Set(tokenScopes);
+            const missingScopes = environmentScopes.filter((scope) => !tokenScopeSet.has(scope));
+            info.scopeInfo = {
+                tokenScopes,
+                environmentScopes,
+                missingScopes,
+            };
+        }
+        return info;
+    }
+    /**
+     * Get internal user tokens (for debugging/status tools)
+     * @internal
+     */
+    getUserTokens() {
+        return this.userTokens;
+    }
+    /**
+     * Get internal app access token cached value (for debugging/status tools)
+     * @internal
+     */
+    getCachedAppAccessToken() {
+        return this.appAccessToken;
+    }
+    /**
+     * Get internal app access token expiry (for debugging/status tools)
+     * @internal
+     */
+    getCachedAppAccessTokenExpiry() {
+        return this.appAccessTokenExpiry;
+    }
+}

package/build/auth/scope-utils.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Utility functions for working with eBay OAuth scopes
+ */
+/**
+ * Result of scope validation
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    warnings: string[];
+    validScopes: string[];
+    invalidScopes: string[];
+}
+/**
+ * Comparison between two sets of scopes
+ */
+export interface ScopeDifference {
+    inBothEnvironments: string[];
+    productionOnly: string[];
+    sandboxOnly: string[];
+}
+/**
+ * Scope requirement information for a tool
+ */
+export interface ScopeRequirement {
+    requiredScopes: string[];
+    optionalScopes?: string[];
+    minimumScope: string;
+    description: string;
+}
+/**
+ * Validate scopes and provide detailed validation results
+ */
+export declare function validateScopesDetailed(scopes: string[], environment: 'production' | 'sandbox'): ValidationResult;
+/**
+ * Get required scopes for a specific tool
+ * This maps tool names to their required eBay OAuth scopes
+ */
+export declare function getRequiredScopesForTool(toolName: string): ScopeRequirement | null;
+/**
+ * Check if a token has all required scopes for a tool
+ */
+export declare function hasRequiredScopes(tokenScopes: string[], requiredScopes: string[]): boolean;
+/**
+ * Get the differences between production and sandbox scopes
+ */
+export declare function getScopeDifferences(): ScopeDifference;
+/**
+ * Format scope for display (remove common prefix for readability)
+ */
+export declare function formatScopeForDisplay(scope: string): string;
+/**
+ * Group scopes by API category
+ */
+export declare function groupScopesByCategory(scopes: string[]): Record<string, string[]>;
+/**
+ * Check if a scope is readonly
+ */
+export declare function isScopeReadonly(scope: string): boolean;
+/**
+ * Get the write version of a readonly scope
+ */
+export declare function getWriteScope(readonlyScope: string): string | null;
+/**
+ * Get the readonly version of a write scope
+ */
+export declare function getReadonlyScope(writeScope: string): string | null;
+/**
+ * Get scope description from scope name
+ */
+export declare function getScopeDescription(scope: string): string;