ebay-mcp 1.4.3

package/build/auth/scope-utils.js

@@ -0,0 +1,304 @@
+/**
+ * Utility functions for working with eBay OAuth scopes
+ */
+import { getDefaultScopes, validateScopes } from '../config/environment.js';
+/**
+ * Validate scopes and provide detailed validation results
+ */
+export function validateScopesDetailed(scopes, environment) {
+    const validation = validateScopes(scopes, environment);
+    const validScopeSet = new Set(getDefaultScopes(environment));
+    const validScopes = [];
+    const invalidScopes = [];
+    scopes.forEach((scope) => {
+        if (validScopeSet.has(scope)) {
+            validScopes.push(scope);
+        }
+        else {
+            invalidScopes.push(scope);
+        }
+    });
+    return {
+        isValid: invalidScopes.length === 0,
+        warnings: validation.warnings,
+        validScopes,
+        invalidScopes,
+    };
+}
+/**
+ * Get required scopes for a specific tool
+ * This maps tool names to their required eBay OAuth scopes
+ */
+export function getRequiredScopesForTool(toolName) {
+    // Scope requirements mapping based on eBay API documentation
+    const scopeMap = {
+        // Inventory Management Tools
+        ebay_get_inventory_items: {
+            requiredScopes: [
+                'https://api.ebay.com/oauth/api_scope/sell.inventory.readonly',
+                'https://api.ebay.com/oauth/api_scope/sell.inventory',
+            ],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.inventory.readonly',
+            description: 'Requires read access to inventory',
+        },
+        ebay_get_inventory_item: {
+            requiredScopes: [
+                'https://api.ebay.com/oauth/api_scope/sell.inventory.readonly',
+                'https://api.ebay.com/oauth/api_scope/sell.inventory',
+            ],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.inventory.readonly',
+            description: 'Requires read access to inventory',
+        },
+        ebay_create_inventory_item: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.inventory'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.inventory',
+            description: 'Requires write access to inventory',
+        },
+        ebay_create_offer: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.inventory'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.inventory',
+            description: 'Requires write access to inventory',
+        },
+        ebay_publish_offer: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.inventory'],
+            optionalScopes: [
+                'https://api.ebay.com/oauth/api_scope/sell.account',
+                'https://api.ebay.com/oauth/api_scope/sell.fulfillment',
+            ],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.inventory',
+            description: 'Requires write access to inventory; policies must exist (sell.account)',
+        },
+        // Order Management Tools
+        ebay_get_orders: {
+            requiredScopes: [
+                'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
+                'https://api.ebay.com/oauth/api_scope/sell.fulfillment',
+            ],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
+            description: 'Requires read access to order fulfillment',
+        },
+        ebay_get_order: {
+            requiredScopes: [
+                'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
+                'https://api.ebay.com/oauth/api_scope/sell.fulfillment',
+            ],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
+            description: 'Requires read access to order fulfillment',
+        },
+        ebay_create_shipping_fulfillment: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.fulfillment'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.fulfillment',
+            description: 'Requires write access to order fulfillment',
+        },
+        ebay_issue_refund: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.fulfillment'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.fulfillment',
+            description: 'Requires write access to order fulfillment',
+        },
+        // Account Management Tools
+        ebay_get_fulfillment_policies: {
+            requiredScopes: [
+                'https://api.ebay.com/oauth/api_scope/sell.account.readonly',
+                'https://api.ebay.com/oauth/api_scope/sell.account',
+            ],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.account.readonly',
+            description: 'Requires read access to account settings',
+        },
+        ebay_create_fulfillment_policy: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.account'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.account',
+            description: 'Requires write access to account settings',
+        },
+        // Marketing Tools
+        ebay_get_campaigns: {
+            requiredScopes: [
+                'https://api.ebay.com/oauth/api_scope/sell.marketing.readonly',
+                'https://api.ebay.com/oauth/api_scope/sell.marketing',
+            ],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.marketing.readonly',
+            description: 'Requires read access to marketing campaigns',
+        },
+        ebay_create_campaign: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.marketing'],
+            optionalScopes: ['https://api.ebay.com/oauth/api_scope/sell.inventory.readonly'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.marketing',
+            description: 'Requires write access to marketing campaigns',
+        },
+        // Analytics Tools
+        ebay_get_traffic_report: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/sell.analytics.readonly'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/sell.analytics.readonly',
+            description: 'Requires read access to analytics',
+        },
+        // Messaging Tools
+        ebay_send_message: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/commerce.message'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/commerce.message',
+            description: 'Requires access to messaging (production only)',
+        },
+        // Feedback Tools
+        ebay_leave_feedback_for_buyer: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/commerce.feedback'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/commerce.feedback',
+            description: 'Requires write access to feedback',
+        },
+        // Identity Tools
+        ebay_get_user: {
+            requiredScopes: ['https://api.ebay.com/oauth/api_scope/commerce.identity.readonly'],
+            minimumScope: 'https://api.ebay.com/oauth/api_scope/commerce.identity.readonly',
+            description: 'Requires read access to user identity',
+        },
+    };
+    return scopeMap[toolName] || null;
+}
+/**
+ * Check if a token has all required scopes for a tool
+ */
+export function hasRequiredScopes(tokenScopes, requiredScopes) {
+    const tokenScopeSet = new Set(tokenScopes);
+    // Check if at least one of the required scopes is present
+    // (Some tools accept either readonly or write scope)
+    return requiredScopes.some((scope) => tokenScopeSet.has(scope));
+}
+/**
+ * Get the differences between production and sandbox scopes
+ */
+export function getScopeDifferences() {
+    const productionScopes = getDefaultScopes('production');
+    const sandboxScopes = getDefaultScopes('sandbox');
+    const productionSet = new Set(productionScopes);
+    const sandboxSet = new Set(sandboxScopes);
+    const inBothEnvironments = [];
+    const productionOnly = [];
+    const sandboxOnly = [];
+    // Find scopes in both
+    productionScopes.forEach((scope) => {
+        if (sandboxSet.has(scope)) {
+            inBothEnvironments.push(scope);
+        }
+        else {
+            productionOnly.push(scope);
+        }
+    });
+    // Find sandbox-only scopes
+    sandboxScopes.forEach((scope) => {
+        if (!productionSet.has(scope)) {
+            sandboxOnly.push(scope);
+        }
+    });
+    return {
+        inBothEnvironments,
+        productionOnly,
+        sandboxOnly,
+    };
+}
+/**
+ * Format scope for display (remove common prefix for readability)
+ */
+export function formatScopeForDisplay(scope) {
+    const prefix = 'https://api.ebay.com/oauth/';
+    if (scope.startsWith(prefix)) {
+        return scope.substring(prefix.length);
+    }
+    return scope;
+}
+/**
+ * Group scopes by API category
+ */
+export function groupScopesByCategory(scopes) {
+    const categories = {
+        sell: [],
+        buy: [],
+        commerce: [],
+        other: [],
+    };
+    scopes.forEach((scope) => {
+        if (scope.includes('/sell.')) {
+            categories.sell.push(scope);
+        }
+        else if (scope.includes('/buy.')) {
+            categories.buy.push(scope);
+        }
+        else if (scope.includes('/commerce.')) {
+            categories.commerce.push(scope);
+        }
+        else {
+            categories.other.push(scope);
+        }
+    });
+    return categories;
+}
+/**
+ * Check if a scope is readonly
+ */
+export function isScopeReadonly(scope) {
+    return scope.includes('.readonly');
+}
+/**
+ * Get the write version of a readonly scope
+ */
+export function getWriteScope(readonlyScope) {
+    if (!isScopeReadonly(readonlyScope)) {
+        return null; // Already a write scope
+    }
+    return readonlyScope.replace('.readonly', '');
+}
+/**
+ * Get the readonly version of a write scope
+ */
+export function getReadonlyScope(writeScope) {
+    if (isScopeReadonly(writeScope)) {
+        return null; // Already a readonly scope
+    }
+    // Not all write scopes have readonly equivalents
+    const hasReadonly = [
+        'sell.inventory',
+        'sell.fulfillment',
+        'sell.account',
+        'sell.marketing',
+        'sell.analytics',
+        'sell.reputation',
+        'sell.stores',
+        'commerce.identity',
+        'commerce.notification.subscription',
+        'commerce.feedback',
+    ];
+    const scopeType = writeScope.split('/').pop();
+    if (scopeType && hasReadonly.some((s) => scopeType.includes(s))) {
+        return `${writeScope}.readonly`;
+    }
+    return null;
+}
+/**
+ * Get scope description from scope name
+ */
+export function getScopeDescription(scope) {
+    // Extract the last part of the scope
+    const parts = scope.split('/');
+    const scopeType = parts[parts.length - 1];
+    const descriptions = {
+        api_scope: 'View public data from eBay',
+        'sell.inventory': 'View and manage your inventory and offers',
+        'sell.inventory.readonly': 'View your inventory and offers',
+        'sell.fulfillment': 'View and manage your order fulfillments',
+        'sell.fulfillment.readonly': 'View your order fulfillments',
+        'sell.account': 'View and manage your account settings',
+        'sell.account.readonly': 'View your account settings',
+        'sell.marketing': 'View and manage your eBay marketing activities',
+        'sell.marketing.readonly': 'View your eBay marketing activities',
+        'sell.analytics.readonly': 'View your selling analytics data',
+        'sell.finances': 'View and manage your payment and order information',
+        'sell.payment.dispute': 'View and manage disputes and related details',
+        'commerce.identity.readonly': 'View basic user information from eBay account',
+        'sell.reputation': 'View and manage your reputation data',
+        'sell.reputation.readonly': 'View your reputation data',
+        'commerce.notification.subscription': 'View and manage event notification subscriptions',
+        'commerce.notification.subscription.readonly': 'View event notification subscriptions',
+        'commerce.feedback': 'View and manage feedback',
+        'commerce.feedback.readonly': 'View feedback',
+        'commerce.message': 'Send and receive messages with buyers/sellers',
+        'sell.stores': 'View and manage eBay stores',
+        'sell.stores.readonly': 'View eBay stores',
+    };
+    return descriptions[scopeType] || `Access to ${scopeType}`;
+}

package/build/auth/token-verifier.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Token verification using OAuth 2.0 Token Introspection (RFC 7662)
+ * and JWT validation
+ */
+import type { VerifiedToken, OAuthServerMetadata } from './oauth-types.js';
+export interface TokenVerifierConfig {
+    /**
+     * OAuth authorization server metadata URL or metadata object
+     */
+    authServerMetadata: string | OAuthServerMetadata;
+    /**
+     * Client ID for introspection endpoint authentication
+     */
+    clientId?: string;
+    /**
+     * Client secret for introspection endpoint authentication
+     */
+    clientSecret?: string;
+    /**
+     * Expected audience (resource server URL)
+     */
+    expectedAudience: string;
+    /**
+     * Required scopes for access
+     */
+    requiredScopes?: string[];
+    /**
+     * Whether to use token introspection (true) or JWT validation (false)
+     * Default: true
+     */
+    useIntrospection?: boolean;
+}
+export declare class TokenVerifier {
+    private config;
+    private metadata;
+    constructor(config: TokenVerifierConfig);
+    /**
+     * Initialize the verifier by loading OAuth server metadata
+     */
+    initialize(): Promise<void>;
+    /**
+     * Verify an access token
+     */
+    verifyToken(token: string): Promise<VerifiedToken>;
+    /**
+     * Verify token using OAuth 2.0 Token Introspection (RFC 7662)
+     */
+    private verifyViaIntrospection;
+    /**
+     * Verify token using JWT validation
+     */
+    private verifyViaJWT;
+    /**
+     * Validate audience claim
+     */
+    private validateAudience;
+}

package/build/auth/token-verifier.js

@@ -0,0 +1,172 @@
+/**
+ * Token verification using OAuth 2.0 Token Introspection (RFC 7662)
+ * and JWT validation
+ */
+import axios from 'axios';
+import * as jose from 'jose';
+export class TokenVerifier {
+    config;
+    metadata = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Initialize the verifier by loading OAuth server metadata
+     */
+    async initialize() {
+        if (typeof this.config.authServerMetadata === 'string') {
+            try {
+                const response = await axios.get(this.config.authServerMetadata);
+                this.metadata = response.data;
+            }
+            catch (error) {
+                throw new Error(`Failed to load OAuth server metadata: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        else {
+            this.metadata = this.config.authServerMetadata;
+        }
+    }
+    /**
+     * Verify an access token
+     */
+    async verifyToken(token) {
+        if (!this.metadata) {
+            throw new Error('Token verifier not initialized');
+        }
+        if (this.config.useIntrospection !== false) {
+            return await this.verifyViaIntrospection(token);
+        }
+        else {
+            return await this.verifyViaJWT(token);
+        }
+    }
+    /**
+     * Verify token using OAuth 2.0 Token Introspection (RFC 7662)
+     */
+    async verifyViaIntrospection(token) {
+        if (!this.metadata) {
+            throw new Error('Token verifier not initialized');
+        }
+        // Check if introspection endpoint is available
+        const introspectionEndpoint = this.metadata.introspection_endpoint;
+        if (!introspectionEndpoint) {
+            throw new Error('Introspection endpoint not available in OAuth server metadata');
+        }
+        // Prepare introspection request
+        const requestData = {
+            token,
+            token_type_hint: 'access_token',
+        };
+        // Add client credentials if provided
+        const headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+        };
+        const params = new URLSearchParams({
+            token: requestData.token,
+        });
+        if (this.config.clientId) {
+            params.set('client_id', this.config.clientId);
+        }
+        if (this.config.clientSecret) {
+            params.set('client_secret', this.config.clientSecret);
+        }
+        // Make introspection request
+        try {
+            const response = await axios.post(introspectionEndpoint, params, {
+                headers,
+            });
+            const data = response.data;
+            // Check if token is active
+            if (!data.active) {
+                throw new Error('Token is not active');
+            }
+            // Validate audience
+            if (!this.validateAudience(data.aud)) {
+                throw new Error(`Invalid audience. Expected: ${this.config.expectedAudience}, Got: ${data.aud}`);
+            }
+            // Validate scopes
+            const scopes = data.scope ? data.scope.split(' ') : [];
+            if (this.config.requiredScopes) {
+                const hasRequiredScopes = this.config.requiredScopes.every((scope) => scopes.includes(scope));
+                if (!hasRequiredScopes) {
+                    throw new Error(`Missing required scopes. Required: ${this.config.requiredScopes.join(', ')}, Got: ${scopes.join(', ')}`);
+                }
+            }
+            return {
+                token,
+                clientId: data.client_id || 'unknown',
+                scopes,
+                expiresAt: data.exp,
+                audience: data.aud,
+                subject: data.sub,
+            };
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                throw new Error(`Token introspection failed: ${error.response?.data?.error_description || error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Verify token using JWT validation
+     */
+    async verifyViaJWT(token) {
+        if (!this.metadata) {
+            throw new Error('Token verifier not initialized');
+        }
+        if (!this.metadata.jwks_uri) {
+            throw new Error('JWKS URI not available in OAuth server metadata');
+        }
+        try {
+            // Get JWKS from authorization server
+            const JWKS = jose.createRemoteJWKSet(new URL(this.metadata.jwks_uri));
+            // Verify JWT
+            const { payload } = await jose.jwtVerify(token, JWKS, {
+                issuer: this.metadata.issuer,
+                audience: this.config.expectedAudience,
+            });
+            // Extract scopes
+            const scopes = typeof payload.scope === 'string'
+                ? payload.scope.split(' ')
+                : Array.isArray(payload.scope)
+                    ? payload.scope
+                    : [];
+            // Validate required scopes
+            if (this.config.requiredScopes) {
+                const hasRequiredScopes = this.config.requiredScopes.every((scope) => scopes.includes(scope));
+                if (!hasRequiredScopes) {
+                    throw new Error(`Missing required scopes. Required: ${this.config.requiredScopes.join(', ')}, Got: ${scopes.join(', ')}`);
+                }
+            }
+            return {
+                token,
+                clientId: payload.client_id || payload.azp || 'unknown',
+                scopes,
+                expiresAt: payload.exp,
+                audience: payload.aud,
+                subject: payload.sub,
+            };
+        }
+        catch (error) {
+            throw new Error(`JWT verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Validate audience claim
+     */
+    validateAudience(audience) {
+        if (!audience) {
+            return false;
+        }
+        const audiences = Array.isArray(audience) ? audience : [audience];
+        const normalizedExpected = this.config.expectedAudience.replace(/\/$/, '');
+        return audiences.some((aud) => {
+            const normalizedAud = aud.replace(/\/$/, '');
+            return (normalizedAud === normalizedExpected ||
+                normalizedAud === normalizedExpected + '/' ||
+                normalizedExpected === normalizedAud + '/');
+        });
+    }
+}

package/build/config/environment.d.ts

@@ -0,0 +1,61 @@
+import type { EbayConfig } from '../types/ebay.js';
+import type { Implementation } from '@modelcontextprotocol/sdk/types.js';
+import { LocaleEnum } from '../types/ebay-enums.js';
+/**
+ * Get default scopes for the specified environment
+ */
+export declare function getDefaultScopes(environment: 'production' | 'sandbox'): string[];
+/**
+ * Validate scopes against environment and return warnings for invalid scopes
+ */
+export declare function validateScopes(scopes: string[], environment: 'production' | 'sandbox'): {
+    warnings: string[];
+    validScopes: string[];
+};
+/**
+ * Validate environment configuration on startup
+ */
+export declare function validateEnvironmentConfig(): {
+    isValid: boolean;
+    warnings: string[];
+    errors: string[];
+};
+export declare function getEbayConfig(): EbayConfig;
+export declare function getBaseUrl(environment: 'production' | 'sandbox'): string;
+/**
+ * Get base URL for Identity API (uses apiz subdomain)
+ */
+export declare function getIdentityBaseUrl(environment: 'production' | 'sandbox'): string;
+/**
+ * Get the OAuth token endpoint URL
+ * @param environment The eBay environment ('production' or 'sandbox')
+ * @returns The token endpoint URL
+ */
+export declare function getAuthUrl(environment: 'production' | 'sandbox'): string;
+/**
+ * Generate the OAuth authorization URL for user consent
+ * @param clientId The client ID of your eBay application.
+ * @param redirectUri The redirect URI configured for your eBay application.
+ * @param environment The eBay environment ('production' or 'sandbox').
+ * @param locale The locale for the authorization page (defaults to en_US).
+ * @param prompt Whether to prompt the user for login or consent (defaults to 'login').
+ * @param responseType The response type for the OAuth flow (defaults to 'code').
+ * @param state An opaque value used to maintain state between the request and callback.
+ *              It is also used to prevent cross-site request forgery.
+ * @param scopes An array of OAuth scopes to request. If not provided, default scopes for the environment will be used.
+ *
+ * @return The generated OAuth authorization URL.
+ *
+ * This URL should be opened in a browser for the user to grant permissions
+ */
+export declare function getAuthUrl(clientId: string, redirectUri: string | undefined, environment: 'production' | 'sandbox', locale?: LocaleEnum, prompt?: 'login' | 'consent', responseType?: 'code', state?: string, scopes?: string[]): string;
+/**
+ * Generate the OAuth authorization URL for user consent
+ * This URL should be opened in a browser for the user to grant permissions
+ *
+ * Note: Scopes are optional - eBay will automatically grant the appropriate scopes
+ * based on your application's keyset configuration if scopes are not specified.
+ */
+export declare function getOAuthAuthorizationUrl(clientId: string, redirectUri: string, // MUST be eBay RuName, NOT a URL
+environment: 'production' | 'sandbox', scopes?: string[], locale?: string, state?: string): string;
+export declare const mcpConfig: Implementation;