ebay-mcp-remote-edition 1.0.0

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-store.js

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { authLogger } from '../utils/logger.js';
+function defaultTokenStorePath() {
+    return process.env.EBAY_TOKEN_STORE_PATH || resolve(process.cwd(), '.ebay-user-tokens.json');
+}
+export class EbayTokenStore {
+    filePath;
+    constructor(filePath = defaultTokenStorePath()) {
+        this.filePath = filePath;
+    }
+    getPath() {
+        return this.filePath;
+    }
+    load() {
+        try {
+            if (!existsSync(this.filePath)) {
+                return null;
+            }
+            const raw = readFileSync(this.filePath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            authLogger.error('Failed to load token store', {
+                path: this.filePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    save(state) {
+        try {
+            mkdirSync(dirname(this.filePath), { recursive: true });
+            writeFileSync(this.filePath, JSON.stringify({
+                ...state,
+                updatedAt: new Date().toISOString(),
+            }, null, 2), 'utf-8');
+        }
+        catch (error) {
+            authLogger.error('Failed to save token store', {
+                path: this.filePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}

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 + '/');
+        });
+    }
+}