ebay-mcp-remote-edition 3.1.1 → 3.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Kenyatta Naji Johnson-Adams
+Copyright (c) 2026 Kenyatta Naji Johnson-Adams
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -101,6 +101,51 @@ EBAY_LOCAL_TLS_CERT_PATH=/path/to/ebay-local.test.pem
 EBAY_LOCAL_TLS_KEY_PATH=/path/to/ebay-local.test-key.pem
 ```
 
+#### ⚠️ Trust the mkcert CA in Node.js (required for MCP clients like Cline)
+
+VS Code's extension host (where Cline runs) uses Node.js for outbound HTTPS requests. Node.js does **not** automatically read macOS's system keychain, so the `ebay-local.test` certificate is not trusted by default. This causes the OAuth token exchange (`POST /sandbox/token`) to fail silently — the browser flow completes, the "Open in VS Code" page appears, but Cline never receives a session token.
+
+**Fix — run these two commands once, then fully quit and reopen VS Code:**
+
+```bash
+# 1. Set for the current macOS session (affects all Dock/Spotlight-launched apps):
+launchctl setenv NODE_EXTRA_CA_CERTS "$(mkcert -CAROOT)/rootCA.pem"
+
+# 2. Create a LaunchAgent so it persists across reboots:
+cat > ~/Library/LaunchAgents/com.local.mkcert-node-trust.plist <<'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.local.mkcert-node-trust</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>launchctl</string><string>setenv</string>
+    <string>NODE_EXTRA_CA_CERTS</string>
+    <string>/Users/YOUR_USERNAME/Library/Application Support/mkcert/rootCA.pem</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+</dict>
+</plist>
+EOF
+launchctl load ~/Library/LaunchAgents/com.local.mkcert-node-trust.plist
+
+# 3. For terminal-launched VS Code — add to ~/.zshrc:
+echo 'export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"' >> ~/.zshrc
+```
+
+> Replace `YOUR_USERNAME` with your actual macOS username in the plist, or use the full path printed by `mkcert -CAROOT`.
+
+After running these commands and **fully quitting VS Code (Cmd+Q on macOS)** and reopening it, Cline's extension host will trust the `ebay-local.test` certificate and the MCP OAuth flow will complete successfully.
+
+**Verify the fix works (without restarting VS Code):**
+```bash
+NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" node -e "
+  require('https').get('https://ebay-local.test:3000/health', r => console.log('TLS OK — status:', r.statusCode)).on('error', e => console.error('TLS FAIL:', e.message));
+"
+# Expected: TLS OK — status: 200
+```
+
 For hosted deployments, register your server's public HTTPS URL instead (e.g. `https://your-server.com/oauth/callback`).
 
 ---
@@ -109,10 +154,10 @@ For hosted deployments, register your server's public HTTPS URL instead (e.g. `h
 
 ### Install
 
-**Option A — npm global install (no build step):**
+**Option A — pnpm global install (no build step):**
 
 ```bash
-npm install -g ebay-mcp-remote-edition
+pnpm install -g ebay-mcp-remote-edition
 ```
 
 **Option B — clone and build (for contributors or self-hosting):**

package/build/auth/multi-user-store.js

@@ -5,8 +5,20 @@ import { createKVStore } from '../auth/kv-store.js';
 const OAUTH_STATE_TTL_S = 15 * 60;
 /** 10 minutes — short-lived MCP authorization code. */
 const AUTH_CODE_TTL_S = 10 * 60;
-/** 30 days — configurable via SESSION_TTL_SECONDS env var. */
-const SESSION_TTL_S = Number(process.env.SESSION_TTL_SECONDS ?? 30 * 24 * 60 * 60);
+/** 30 days — default; configurable via SESSION_TTL_SECONDS env var. */
+const SESSION_TTL_FALLBACK_S = 30 * 24 * 60 * 60;
+const _rawSessionTtl = process.env.SESSION_TTL_SECONDS;
+const SESSION_TTL_S = (() => {
+    if (_rawSessionTtl === undefined || _rawSessionTtl.trim() === '') {
+        return SESSION_TTL_FALLBACK_S;
+    }
+    const parsed = Number(_rawSessionTtl);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        console.warn(`[multi-user-store] SESSION_TTL_SECONDS="${_rawSessionTtl}" is invalid; falling back to ${SESSION_TTL_FALLBACK_S}s (30 days)`);
+        return SESSION_TTL_FALLBACK_S;
+    }
+    return Math.floor(parsed);
+})();
 /** 18 months — default fallback when no refresh token expiry is available. */
 const DEFAULT_REFRESH_TOKEN_TTL_S = 18 * 30 * 24 * 60 * 60;
 function secondsFromNow(ttlSeconds) {
@@ -32,7 +44,7 @@ export class MultiUserAuthStore {
      * `lastUsedAt` once per TOUCH_THROTTLE_MS (default: 1 hour).
      */
     sessionTouchCache = new Map();
-    static TOUCH_THROTTLE_MS = 60 * 60 * 1_000; // 1 hour
+    static touchThrottleMs = 60 * 60 * 1_000; // 1 hour
     stateKey(state) {
         return `oauth_state:${state}`;
     }
@@ -55,6 +67,12 @@ export class MultiUserAuthStore {
         await this.kv.put(this.stateKey(state), record, OAUTH_STATE_TTL_S);
         return record;
     }
+    async getOAuthState(state) {
+        return await this.kv.get(this.stateKey(state));
+    }
+    async deleteOAuthState(state) {
+        await this.kv.delete(this.stateKey(state));
+    }
     async consumeOAuthState(state) {
         const key = this.stateKey(state);
         const record = await this.kv.get(key);
@@ -110,7 +128,7 @@ export class MultiUserAuthStore {
         // Skip the KV write entirely if we touched this session recently.
         // The in-memory cache in CloudflareKVStore already keeps reads free,
         // so the only cost we're avoiding here is the unnecessary KV PUT.
-        if (lastTouched !== undefined && now - lastTouched < MultiUserAuthStore.TOUCH_THROTTLE_MS) {
+        if (lastTouched !== undefined && now - lastTouched < MultiUserAuthStore.touchThrottleMs) {
             return;
         }
         const record = await this.getSession(sessionToken);
@@ -139,13 +157,14 @@ export class MultiUserAuthStore {
         await this.kv.delete(this.sessionKey(sessionToken));
     }
     // ── RFC 7591 Dynamic Client Registration ──────────────────────────────────
-    async registerClient(redirectUris, clientName) {
+    async registerClient(redirectUris, clientName, environment) {
         const clientId = randomUUID();
         const record = {
             clientId,
             redirectUris,
             clientName,
             createdAt: new Date().toISOString(),
+            ...(environment ? { environment } : {}),
         };
         await this.kv.put(`client:${clientId}`, record);
         return record;
@@ -162,13 +181,25 @@ export class MultiUserAuthStore {
      * An existing record for `clientId` is overwritten only if the supplied
      * `redirectUri` is not already listed (additive merge otherwise).
      */
-    async registerClientWithId(clientId, redirectUris, clientName) {
+    /**
+     * @param environment  Optional env to tag the client with.  When provided,
+     *   the environment is persisted on the record so that the root /authorize
+     *   endpoint can use it as a fallback even when no ?env= query param is
+     *   present.  If the existing record already has a different environment
+     *   the new value wins (e.g. re-registering via /sandbox/authorize should
+     *   override a stale "production" tag).
+     */
+    async registerClientWithId(clientId, redirectUris, clientName, environment) {
         const existing = await this.kv.get(`client:${clientId}`);
         const now = new Date().toISOString();
         if (existing) {
-            // Merge any new redirect URIs into the existing record
+            // Merge any new redirect URIs and update the env tag when provided.
             const merged = Array.from(new Set([...existing.redirectUris, ...redirectUris]));
-            const updated = { ...existing, redirectUris: merged };
+            const updated = {
+                ...existing,
+                redirectUris: merged,
+                ...(environment ? { environment } : {}),
+            };
             await this.kv.put(`client:${clientId}`, updated);
             return updated;
         }
@@ -177,6 +208,7 @@ export class MultiUserAuthStore {
             redirectUris,
             clientName,
             createdAt: now,
+            ...(environment ? { environment } : {}),
         };
         await this.kv.put(`client:${clientId}`, record);
         return record;

package/build/auth/oauth.js

@@ -1,5 +1,5 @@
 import axios from 'axios';
-import { getBaseUrl } from '../config/environment.js';
+import { getOAuthTokenBaseUrl } from '../config/environment.js';
 import { MultiUserAuthStore } from '../auth/multi-user-store.js';
 export class EbayOAuthClient {
     config;
@@ -8,15 +8,20 @@ export class EbayOAuthClient {
     appAccessTokenExpiry = 0;
     userTokens = null;
     authStore = new MultiUserAuthStore();
+    authSource = null;
     constructor(config, context) {
         this.config = config;
         this.context = context;
     }
+    getTokenEndpoint() {
+        return `${getOAuthTokenBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+    }
     async initialize() {
         if (this.context?.userId && this.context.environment) {
             const stored = await this.authStore.getUserTokens(this.context.userId, this.context.environment);
             if (stored?.tokenData) {
                 this.userTokens = stored.tokenData;
+                this.authSource = 'stored_user_tokens';
                 return;
             }
         }
@@ -24,7 +29,7 @@ export class EbayOAuthClient {
         const envRefreshToken = process.env.EBAY_USER_REFRESH_TOKEN;
         if (envRefreshToken) {
             try {
-                const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+                const authUrl = this.getTokenEndpoint();
                 const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
                 const response = await axios.post(authUrl, new URLSearchParams({
                     grant_type: 'refresh_token',
@@ -50,6 +55,7 @@ export class EbayOAuthClient {
                         : now + 18 * 30 * 24 * 60 * 60 * 1000,
                     scope: tokenData.scope,
                 };
+                this.authSource = 'env_refresh_token_fallback';
             }
             catch {
                 // If refresh fails, leave userTokens as null
@@ -99,13 +105,14 @@ export class EbayOAuthClient {
             userAccessTokenExpiry: accessTokenExpiry ?? now + 7200 * 1000,
             userRefreshTokenExpiry: refreshTokenExpiry ?? now + 18 * 30 * 24 * 60 * 60 * 1000,
         };
+        this.authSource = 'manual_set_user_tokens';
         await this.persistUserTokens();
     }
     async getOrRefreshAppAccessToken() {
         if (this.appAccessToken && Date.now() < this.appAccessTokenExpiry) {
             return this.appAccessToken;
         }
-        const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const authUrl = this.getTokenEndpoint();
         const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
         const response = await axios.post(authUrl, new URLSearchParams({
             grant_type: 'client_credentials',
@@ -124,7 +131,7 @@ export class EbayOAuthClient {
         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 tokenUrl = this.getTokenEndpoint();
         const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
         try {
             const response = await axios.post(tokenUrl, new URLSearchParams({
@@ -150,6 +157,7 @@ export class EbayOAuthClient {
                 userRefreshTokenExpiry: now + tokenData.refresh_token_expires_in * 1000,
                 scope: tokenData.scope,
             };
+            this.authSource = 'authorization_code_exchange';
             await this.persistUserTokens();
             return tokenData;
         }
@@ -170,7 +178,7 @@ export class EbayOAuthClient {
         if (!this.userTokens) {
             throw new Error('No user tokens available to refresh');
         }
-        const authUrl = `${getBaseUrl(this.config.environment)}/identity/v1/oauth2/token`;
+        const authUrl = this.getTokenEndpoint();
         const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
         const response = await axios.post(authUrl, new URLSearchParams({
             grant_type: 'refresh_token',
@@ -198,6 +206,24 @@ export class EbayOAuthClient {
         };
         await this.persistUserTokens();
     }
+    getAuthDebugInfo() {
+        return {
+            tokenEndpoint: this.getTokenEndpoint(),
+            environment: this.config.environment,
+            hasClientId: this.config.clientId.trim().length > 0,
+            hasClientSecret: this.config.clientSecret.trim().length > 0,
+            hasRefreshToken: !!this.userTokens?.userRefreshToken,
+            hasAccessToken: !!this.userTokens?.userAccessToken,
+            hasRedirectUri: !!this.config.redirectUri,
+            ...(this.userTokens?.userRefreshTokenExpiry
+                ? { refreshTokenExpiry: this.userTokens.userRefreshTokenExpiry }
+                : {}),
+            ...(this.userTokens?.userAccessTokenExpiry
+                ? { accessTokenExpiry: this.userTokens.userAccessTokenExpiry }
+                : {}),
+            ...(this.authSource ? { source: this.authSource } : {}),
+        };
+    }
     isAuthenticated() {
         if (this.userTokens && !this.isUserAccessTokenExpired(this.userTokens)) {
             return true;

package/build/config/environment.js

@@ -130,26 +130,59 @@ export function getHostedOauthScopes(environment) {
         'https://api.ebay.com/oauth/api_scope/commerce.message',
         'https://api.ebay.com/oauth/api_scope/commerce.feedback',
         'https://api.ebay.com/oauth/api_scope/commerce.shipping',
-        'https://api.ebay.com/oauth/api_scope/sell.order.read',
-        'https://api.ebay.com/oauth/api_scope/sell.order',
-        'https://api.ebay.com/oauth/api_scope/sell.auction.read',
-        'https://api.ebay.com/oauth/api_scope/sell.offer.read',
-        'https://api.ebay.com/oauth/api_scope/sell.offer',
-        'https://api.ebay.com/oauth/api_scope/sell.return.read',
-        'https://api.ebay.com/oauth/api_scope/sell.return',
-        'https://api.ebay.com/oauth/api_scope/sell.refund.read',
-        'https://api.ebay.com/oauth/api_scope/sell.resolution.read',
-        'https://api.ebay.com/oauth/api_scope/sell.inquiry.read',
-        'https://api.ebay.com/oauth/api_scope/sell.inquiry',
-        'https://api.ebay.com/oauth/api_scope/sell.cancellation.read',
-        'https://api.ebay.com/oauth/api_scope/sell.cancellation',
-        'https://api.ebay.com/oauth/api_scope/commerce.usernote',
     ];
 }
 export function getConfiguredEnvironment() {
     const env = process.env.EBAY_ENVIRONMENT || process.env.EBAY_DEFAULT_ENVIRONMENT || 'production';
     return env === 'sandbox' ? 'sandbox' : 'production';
 }
+/**
+ * Parse an eBay RuName string to detect whether it belongs to production or
+ * sandbox.  eBay encodes the environment in a dedicated segment of the RuName:
+ *
+ *   CompanyName-AppNickname-AppName-**PR**-ID   → production
+ *   CompanyName-AppNickname-AppName-**SB**-ID   → sandbox
+ *
+ * @returns `'production'` | `'sandbox'` | `null` (unknown / not detectable)
+ */
+export function ruNameToEnvironment(ruName) {
+    if (!ruName)
+        return null;
+    // Look for a word boundary -PR- or -SB- anywhere in the string.
+    // Use exact dash-delimited segment matching to avoid false positives (e.g.
+    // "PROMO" or "SUBSCRIBE" being mis-detected).
+    if (/-PR-/i.test(ruName))
+        return 'production';
+    if (/-SB-/i.test(ruName))
+        return 'sandbox';
+    return null;
+}
+/**
+ * Validate that the credentials configured for `environment` actually match
+ * the requested environment by inspecting the RuName segment.
+ *
+ * Returns an object describing whether the credentials look correct and any
+ * human-readable warning or error message.
+ */
+export function validateCredentialsForEnvironment(environment) {
+    const config = getEbayConfig(environment);
+    const ruName = config.redirectUri;
+    const detectedEnv = ruNameToEnvironment(ruName);
+    if (detectedEnv === null) {
+        // Can't tell from the RuName — treat as valid (no info to contradict it).
+        return { valid: true, detectedEnv: null };
+    }
+    if (detectedEnv !== environment) {
+        return {
+            valid: false,
+            detectedEnv,
+            error: `Credential mismatch: the RuName "${ruName}" belongs to ${detectedEnv} ` +
+                `but the request targets ${environment}. ` +
+                `Check EBAY_${environment.toUpperCase()}_RUNAME (or EBAY_RUNAME).`,
+        };
+    }
+    return { valid: true, detectedEnv };
+}
 export function validateScopes(scopes, environment) {
     const validScopes = getDefaultScopes(environment);
     const validScopeSet = new Set(validScopes);
@@ -256,9 +289,19 @@ export function getEbayConfig(environmentOverride) {
         appAccessToken: process.env.EBAY_APP_ACCESS_TOKEN ?? '',
     };
 }
+export function getValidationRunnerUserId(environment) {
+    const envSpecific = environment === 'production'
+        ? process.env.VALIDATION_RUNNER_USER_ID_PRODUCTION
+        : process.env.VALIDATION_RUNNER_USER_ID_SANDBOX;
+    const resolved = (envSpecific ?? process.env.VALIDATION_RUNNER_USER_ID ?? '').trim();
+    return resolved || null;
+}
 export function getBaseUrl(environment) {
     return environment === 'production' ? 'https://api.ebay.com' : 'https://api.sandbox.ebay.com';
 }
+export function getOAuthTokenBaseUrl(environment) {
+    return environment === 'production' ? 'https://api.ebay.com' : 'https://api.sandbox.ebay.com';
+}
 export function getIdentityBaseUrl(environment) {
     return environment === 'production' ? 'https://apiz.ebay.com' : 'https://apiz.sandbox.ebay.com';
 }

package/build/scripts/{run-with-local-env.js → env-check.js}

@@ -11,7 +11,7 @@ function isHostedEnvironment() {
 function main() {
     const args = process.argv.slice(2);
     if (args.length === 0) {
-        throw new Error('Usage: tsx src/scripts/run-with-local-env.ts <command> [args...]');
+        throw new Error('Usage: tsx src/scripts/env-check.ts <command> [args...]');
     }
     const hosted = isHostedEnvironment();
     const [command, ...commandArgs] = args;