ebay-mcp-remote-edition 2.0.16 → 3.1.0

package/README.md

@@ -21,7 +21,7 @@ This fork of [Yosef Hayim's eBay MCP](https://github.com/YosefHayim/ebay-mcp) pr
 
 - Hosted Streamable HTTP MCP deployment mode for remote server deployment
 - Multi-user server-side eBay OAuth for both production and sandbox
-- Cloudflare KV-backed storage for:
+- Cloudflare KV / Upstash Redis-backed storage for:
   - OAuth state
   - user token records
   - session records
@@ -32,6 +32,8 @@ This fork of [Yosef Hayim's eBay MCP](https://github.com/YosefHayim/ebay-mcp) pr
 - `GET /whoami` endpoint for session-bound identity lookup
 - Optional `OAUTH_START_KEY` protection for `/oauth/start`
 - **MCP OAuth 2.1 authorization server** — Cline and other MCP clients that support OAuth discovery (`/.well-known/oauth-authorization-server`, `POST /register`, `GET /authorize`, `POST /token`) can authenticate fully automatically via browser eBay OAuth with no manual token pasting
+- **Environment-scoped route trees** — `/sandbox/mcp` and `/production/mcp` hard-bind their eBay environment; no `?env=` query param needed. Matching scoped discovery, register, authorize, token, and oauth/start endpoints included. Legacy `/mcp` kept for backward compatibility
+- **TTL-aligned session and token records** — Every stored record (`OAuthState`, `AuthCode`, `Session`, `UserToken`) now includes an `expiresAt` ISO timestamp and passes the matching TTL to the KV/Redis backend so application expiry and Redis key expiry are always in sync. Session TTL defaults to 30 days and is configurable via `SESSION_TTL_SECONDS`
 
 ---
 
@@ -124,7 +126,32 @@ For official eBay API support, please refer to the [eBay Developer Program](http
 1. Create a free [eBay Developer Account](https://developer.ebay.com/)
 2. Generate application keys in the [Developer Portal](https://developer.ebay.com/my/keys)
 3. Save your **Client ID** and **Client Secret**
-4. Configure environment-specific RuNames for production and sandbox as needed
+4. Configure a **RuName** (Redirect URL Name) for each environment you plan to use
+
+> **Local HTTPS callback URL (required by eBay)**
+>
+> eBay requires an **HTTPS** callback URL. For local development, use [mkcert](https://github.com/FiloSottile/mkcert) to create a locally-trusted certificate so your dev machine can serve HTTPS.
+>
+> **One-time mkcert setup (macOS):**
+> ```bash
+> brew install mkcert nss          # nss adds Firefox trust support
+> mkcert -install                  # installs local CA into system trust store
+> mkcert ebay-local.test           # creates ebay-local.test.pem + ebay-local.test-key.pem
+> echo "127.0.0.1  ebay-local.test" | sudo tee -a /etc/hosts
+> ```
+>
+> In the eBay Developer Portal, register **`https://ebay-local.test:3000/oauth/callback`** as the callback URL under **User Tokens → Add RuName**. eBay will generate a RuName string (e.g. `YourApp-YourApp-SBX-abcdefg`). Copy that RuName into `EBAY_RUNAME` (or `EBAY_SANDBOX_RUNAME` / `EBAY_PRODUCTION_RUNAME`).
+>
+> Then add to your `.env`:
+> ```
+> PUBLIC_BASE_URL=https://ebay-local.test:3000
+> EBAY_LOCAL_TLS_CERT_PATH=/path/to/ebay-local.test.pem
+> EBAY_LOCAL_TLS_KEY_PATH=/path/to/ebay-local.test-key.pem
+> ```
+>
+> The server automatically starts an HTTPS callback listener when `PUBLIC_BASE_URL` begins with `https://`.
+>
+> **Note:** `EBAY_RUNAME` is an eBay-generated string (the RuName), **not** the callback URL itself. The callback URL is set via `PUBLIC_BASE_URL`. If your eBay app was previously configured only with a hosted callback URL, you will need to add the local URL as an additional RuName in the portal — eBay currently only allows one OAuth-enabled RuName per app at a time.
 
 ### 2. Install
 
@@ -151,6 +178,30 @@ pnpm install
 pnpm run build
 ```
 
+### Environment management with dotenvx
+
+`dotenvx` is for local env workflows only.
+
+Hosted/server platforms should provide environment variables directly.
+For local development, the standard runtime scripts automatically load `.env`
+through dotenvx unless a hosted environment is detected.
+
+Common commands:
+
+```bash
+pnpm run env:encrypt
+pnpm run env:decrypt
+pnpm run env:run -- pnpm run dev:http
+```
+
+This lets you keep a local `.env` for development while also supporting
+encrypted env files for sharing or deployment workflows.
+
+The built-in runtime scripts now behave like this:
+
+- local machine → load `.env` via dotenvx automatically
+- hosted platform (for example `RENDER=true`) → use platform-provided env vars directly
+
 ### 3. Run Local Setup Wizard
 
 For local/STDIO usage after cloning:
@@ -176,6 +227,8 @@ The configs below show both. Supply your eBay credentials either as `env` fields
 
 > **Getting your credentials:** Run `pnpm run setup` in the cloned repo — it completes the OAuth flow and writes `EBAY_USER_REFRESH_TOKEN` to `.env`.
 
+> **`EBAY_RUNAME` is a RuName string, not a URL.** It looks like `YourApp-YourApp-SBX-abcdefg`. To obtain one, register your HTTPS callback URL in the [eBay Developer Portal](https://developer.ebay.com/my/auth) under **User Tokens → Add RuName**, then copy the generated string. See [Step 1](#1-get-ebay-credentials) for the full setup guide including mkcert local HTTPS. `EBAY_REDIRECT_URI` is still accepted as a legacy alias for `EBAY_RUNAME`.
+
 ### Cline
 
 Config file location:  
@@ -352,20 +405,26 @@ pnpm install && pnpm run build
 pnpm run start:http
 ```
 
+On hosted platforms, this uses the platform env directly and does not try to load local `.env` files.
+
 ### Recommended Render environment variables
 
 ```bash
 PORT=
+MCP_HOST=0.0.0.0
 NODE_VERSION=
 PUBLIC_BASE_URL=https://your-server.com
 EBAY_CONFIG_FILE=/etc/secrets/ebay-config.json
 EBAY_DEFAULT_ENVIRONMENT=sandbox|production
-EBAY_TOKEN_STORE_BACKEND=cloudflare-kv
+EBAY_TOKEN_STORE_BACKEND=cloudflare-kv|upstash-redis
 CLOUDFLARE_ACCOUNT_ID=ID
 CLOUDFLARE_KV_NAMESPACE_ID=ID
 CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
+UPSTASH_REDIS_REST_URL=https://...upstash.io
+UPSTASH_REDIS_REST_TOKEN=your-upstash-rest-token
 ADMIN_API_KEY=your-admin-api-key
 OAUTH_START_KEY=optional-shared-secret-for-oauth-start
+SESSION_TTL_SECONDS=2592000      # optional, default 30 days (2592000 s)
 EBAY_MARKETPLACE_ID=EBAY_COUNTRY
 EBAY_CONTENT_LANGUAGE=lang-COUNTRY
 EBAY_LOG_LEVEL=info
@@ -404,22 +463,25 @@ Render mounts it at:
 
 ### OAuth flows
 
-Start production OAuth:
+**Preferred — environment-scoped paths (no `?env=` needed):**
 
 ```text
-/oauth/start?env=production
+/sandbox/oauth/start        # always sandbox
+/production/oauth/start     # always production
 ```
 
-Start sandbox OAuth:
+**Legacy — `?env=` query param (also still supported):**
 
 ```text
 /oauth/start?env=sandbox
+/oauth/start?env=production
 ```
 
-If `OAUTH_START_KEY` is configured, include either:
+If `OAUTH_START_KEY` is configured, include it as a query param or header:
 
 ```text
-/oauth/start?env=production&key=YOUR_OAUTH_START_KEY
+/sandbox/oauth/start?key=YOUR_OAUTH_START_KEY
+/production/oauth/start?key=YOUR_OAUTH_START_KEY
 ```
 
 or send:
@@ -430,7 +492,7 @@ X-OAuth-Start-Key: YOUR_OAUTH_START_KEY
 
 ### Hosted session token usage
 
-After successful callback, the app issues a session token and displays it in a copy-friendly callback page.
+After successful callback, the app issues a session token and stores it in the configured persistent backend (Cloudflare KV or Upstash Redis), then displays it in a copy-friendly callback page.
 
 Use it in your MCP client:
 
@@ -444,7 +506,7 @@ For Make/Zapier/TypingMind anywhere where Remote MCP is accepted, the practical
 2. copy the returned session token from the callback page
 3. paste it into the platform's API Key / Access token field
 
-Normal MCP usage should not open a browser window once a valid hosted session token already exists.
+Normal MCP usage should not open a browser window once a valid hosted session token already exists in the configured persistent store.
 
 ### Admin endpoints
 
@@ -467,20 +529,28 @@ GET /whoami
 Authorization: Bearer <session-token>
 ```
 
-### MCP endpoint
+### MCP endpoints
+
+**Preferred — environment-scoped (hard-binds the eBay environment):**
+
+```text
+POST/GET/DELETE /sandbox/mcp        # always sandbox
+POST/GET/DELETE /production/mcp     # always production
+```
+
+Each scoped path has its own `/.well-known/oauth-authorization-server` so MCP clients that support OAuth discovery (Cline, etc.) automatically use the correct environment.
+
+**Legacy — auto-resolves environment from `?env=` or `EBAY_ENVIRONMENT`:**
 
 ```text
-POST /mcp
-GET /mcp
-DELETE /mcp
+POST/GET/DELETE /mcp
 ```
 
-#### Initial auth behavior
+#### Auth behavior (all paths)
 
-- `GET /mcp` without a valid Bearer token redirects into browser OAuth
-- default environment is production
-- sandbox can be requested with `?env=sandbox`
-- `POST /mcp` without a valid Bearer token returns an auth-required JSON response
+- `GET /mcp` (or scoped variant) without a valid Bearer token redirects into browser OAuth via the matching `oauth/start` path
+- `POST /mcp` without a valid Bearer token returns a structured `401` JSON response with an `authorization_url` field
+- Scoped paths return their hard-bound environment in every error response so the client can pre-fill the correct OAuth start URL
 
 This means browser-driven onboarding works cleanly, while protocol clients can still receive a structured auth response.
 
@@ -504,37 +574,70 @@ Replace `https://your-server.com` with your actual `PUBLIC_BASE_URL`.
 
 ### Cline (recommended — full OAuth auto-discovery)
 
-Cline supports OAuth 2.1 discovery natively. Just point it at the MCP endpoint and it handles everything:
+Cline supports OAuth 2.1 discovery natively. Point it at an environment-scoped MCP endpoint and it handles everything automatically — including fetching the correct discovery document, registering itself, opening the eBay browser login, and storing the session token.
+
+**Sandbox:**
 
 ```json
 {
   "mcpServers": {
-    "ebay": {
-      "url": "https://your-server.com/mcp"
+    "ebay-sandbox": {
+      "url": "https://your-server.com/sandbox/mcp"
+    }
+  }
+}
+```
+
+**Production:**
+
+```json
+{
+  "mcpServers": {
+    "ebay-production": {
+      "url": "https://your-server.com/production/mcp"
     }
   }
 }
 ```
 
 **What happens automatically:**
-1. Cline fetches `/.well-known/oauth-authorization-server` to discover the auth server.
-2. It registers itself at `POST /register` (Dynamic Client Registration).
-3. Your browser opens `GET /authorize`, which redirects to eBay's login page.
+1. Cline fetches `/sandbox/.well-known/oauth-authorization-server` (or `/production/...`) to discover the scoped auth server.
+2. It registers itself at `POST /sandbox/register`.
+3. Your browser opens `GET /sandbox/authorize`, which redirects to eBay's sandbox login page.
 4. After you grant access, eBay redirects to `/oauth/callback`, which issues an MCP auth code and sends it back to Cline.
-5. Cline exchanges the code at `POST /token` for a session token and stores it.
-6. All subsequent `/mcp` requests are authenticated automatically.
+5. Cline exchanges the code at `POST /sandbox/token` for a session token and stores it.
+6. All subsequent `/sandbox/mcp` requests are authenticated automatically.
+
+> **Legacy `?env=` URL** — If you prefer a single endpoint, `https://your-server.com/mcp` still works with environment auto-detection, but the env-scoped paths are recommended for unambiguous behaviour.
 
 > **`OAUTH_START_KEY` note:** If your server has `OAUTH_START_KEY` set, the `/authorize` endpoint also requires it. You can temporarily disable it for first-time client setup, or consult your server operator for the key.
 
 ### Claude Desktop (HTTP remote with pre-obtained session token)
 
-Claude Desktop's remote MCP support requires an explicit `Authorization` header. Complete the browser OAuth flow at `https://your-server.com/oauth/start` first to get your session token, then configure:
+Claude Desktop's remote MCP support requires an explicit `Authorization` header. Complete the browser OAuth flow at the appropriate env-scoped start URL first, then configure:
+
+**Sandbox:**
 
 ```json
 {
   "mcpServers": {
-    "ebay": {
-      "url": "https://your-server.com/mcp",
+    "ebay-sandbox": {
+      "url": "https://your-server.com/sandbox/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_SESSION_TOKEN"
+      }
+    }
+  }
+}
+```
+
+**Production:**
+
+```json
+{
+  "mcpServers": {
+    "ebay-production": {
+      "url": "https://your-server.com/production/mcp",
       "headers": {
         "Authorization": "Bearer YOUR_SESSION_TOKEN"
       }
@@ -548,8 +651,8 @@ Claude Desktop's remote MCP support requires an explicit `Authorization` header.
 ```json
 {
   "mcpServers": {
-    "ebay": {
-      "url": "https://your-server.com/mcp",
+    "ebay-sandbox": {
+      "url": "https://your-server.com/sandbox/mcp",
       "headers": {
         "Authorization": "Bearer YOUR_SESSION_TOKEN"
       }
@@ -562,11 +665,11 @@ Claude Desktop's remote MCP support requires an explicit `Authorization` header.
 
 These platforms use a fixed token field. To connect:
 
-1. Open `https://your-server.com/oauth/start?env=production` in a browser.
+1. Open `https://your-server.com/production/oauth/start` (or `/sandbox/oauth/start`) in a browser.
 2. Complete the eBay login flow.
 3. Copy the session token from the confirmation page.
 4. Paste it as your **API Key / Bearer token** in the platform's MCP connector settings.
-5. Set the MCP endpoint URL to `https://your-server.com/mcp`.
+5. Set the MCP endpoint URL to `https://your-server.com/production/mcp` (or `/sandbox/mcp`).
 
 ---
 
@@ -586,6 +689,37 @@ EBAY_CONTENT_LANGUAGE=lang_COUNTRY
 EBAY_USER_REFRESH_TOKEN=your_refresh_token
 ```
 
+Other supported env vars used by the current runtime:
+
+```bash
+MCP_HOST=0.0.0.0                              # optional HTTP bind host
+EBAY_TOKEN_STORE_PATH=.ebay-user-tokens.json  # legacy single-user file token store path
+SESSION_TTL_SECONDS=2592000                   # hosted mode: session token TTL (default 30 days)
+```
+
+Notes:
+- `EBAY_TOKEN_STORE_PATH` is part of the older local file-token-store path and is **not** used by the hosted multi-user KV/Redis auth flow.
+
+Token env vars such as `EBAY_USER_REFRESH_TOKEN`, `EBAY_USER_ACCESS_TOKEN`, and `EBAY_APP_ACCESS_TOKEN`
+should be treated as local single-user inputs or explicit manual override flows.
+In hosted multi-user mode, OAuth state, user tokens, and session tokens are persisted in the configured
+remote store (Cloudflare KV or Upstash Redis), not in environment variables.
+
+For multi-user local or hosted deployments, use a persistent auth store:
+
+- `EBAY_TOKEN_STORE_BACKEND=cloudflare-kv`, or
+- `EBAY_TOKEN_STORE_BACKEND=upstash-redis`
+
+Use `memory` only for tests or throwaway dev sessions, since all OAuth state,
+user tokens, and session tokens are lost on restart.
+
+Backend selection is driven by `EBAY_TOKEN_STORE_BACKEND` explicitly. Credentials alone do not select the backend:
+
+- `EBAY_TOKEN_STORE_BACKEND=cloudflare-kv` → Cloudflare KV
+- `EBAY_TOKEN_STORE_BACKEND=upstash-redis` → Upstash Redis
+
+If the selected backend is missing required credentials, the server now fails loudly at startup instead of silently appearing to use the wrong store.
+
 ### OAuth Authentication
 
 **Client Credentials:** lower-rate, application-level access.

package/build/auth/kv-store.js

@@ -1,4 +1,5 @@
 import axios from 'axios';
+import { Redis } from '@upstash/redis';
 /**
  * Purely in-memory KV store with optional per-entry TTL.
  * Useful for local development, single-user setups, or when
@@ -48,6 +49,9 @@ export class CloudflareKVStore {
         this.accountId = process.env.CLOUDFLARE_ACCOUNT_ID || '';
         this.namespaceId = process.env.CLOUDFLARE_KV_NAMESPACE_ID || '';
         const apiToken = process.env.CLOUDFLARE_API_TOKEN || '';
+        if (!this.accountId || !this.namespaceId || !apiToken) {
+            throw new Error('Cloudflare KV backend selected, but CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_KV_NAMESPACE_ID, and CLOUDFLARE_API_TOKEN must all be set.');
+        }
         this.client = axios.create({
             baseURL: `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/storage/kv/namespaces/${this.namespaceId}`,
             headers: {
@@ -106,6 +110,60 @@ export class CloudflareKVStore {
         this.cache.clear();
     }
 }
+// ── Upstash Redis backend ────────────────────────────────────────────────────
+/**
+ * Upstash Redis REST API backend with an in-memory read-through cache.
+ * Used when EBAY_TOKEN_STORE_BACKEND=upstash-redis.
+ */
+export class UpstashRedisKVStore {
+    backendName = 'UpstashRedisKVStore';
+    client;
+    cache = new Map();
+    cacheTtlMs;
+    constructor(cacheTtlMs = 5 * 60 * 1_000) {
+        this.cacheTtlMs = cacheTtlMs;
+        const url = process.env.UPSTASH_REDIS_REST_URL || '';
+        const token = process.env.UPSTASH_REDIS_REST_TOKEN || '';
+        if (!url || !token) {
+            throw new Error('Upstash Redis backend selected, but UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN must both be set.');
+        }
+        this.client = new Redis({ url, token });
+    }
+    isCacheValid(entry) {
+        return Date.now() < entry.expiresAt;
+    }
+    async get(key) {
+        const cached = this.cache.get(key);
+        if (cached && this.isCacheValid(cached)) {
+            return cached.value;
+        }
+        const value = await this.client.get(key);
+        this.cache.set(key, { value, expiresAt: Date.now() + this.cacheTtlMs });
+        return value ?? null;
+    }
+    async put(key, value, expirationTtl) {
+        if (expirationTtl !== undefined) {
+            await this.client.set(key, value, { ex: expirationTtl });
+        }
+        else {
+            await this.client.set(key, value);
+        }
+        const cacheTtl = expirationTtl
+            ? Math.min(expirationTtl * 1_000, this.cacheTtlMs)
+            : this.cacheTtlMs;
+        this.cache.set(key, { value, expiresAt: Date.now() + cacheTtl });
+    }
+    async delete(key) {
+        await this.client.del(key);
+        this.cache.delete(key);
+    }
+    invalidate(key) {
+        this.cache.delete(key);
+    }
+    flushCache() {
+        this.cache.clear();
+    }
+}
 // ── Singleton factory ─────────────────────────────────────────────────────────
 /**
  * Process-level singleton KV store.
@@ -126,8 +184,9 @@ let _kvStoreSingleton = null;
  * Returns (or lazily creates) the process-wide KV store singleton based on the
  * EBAY_TOKEN_STORE_BACKEND environment variable:
  *
- *   memory        → InMemoryKVStore  (no external dependencies, data lost on restart)
- *   cloudflare-kv → CloudflareKVStore (default; requires CLOUDFLARE_* env vars)
+ *   memory         → InMemoryKVStore   (no external dependencies, data lost on restart)
+ *   cloudflare-kv  → CloudflareKVStore (requires CLOUDFLARE_* env vars)
+ *   upstash-redis  → UpstashRedisKVStore (requires UPSTASH_REDIS_REST_* env vars)
  *
  * If the variable is unset or unrecognised, defaults to cloudflare-kv so that
  * existing hosted deployments continue to work without any config change.
@@ -146,6 +205,13 @@ export function createKVStore() {
             _kvStoreSingleton = new InMemoryKVStore();
             break;
         }
+        case 'upstash-redis':
+        case 'upstash':
+        case 'redis': {
+            console.log(`[kv-store] EBAY_TOKEN_STORE_BACKEND="${rawEnv ?? ''}" → using UpstashRedisKVStore (url="${process.env.UPSTASH_REDIS_REST_URL ?? '(unset)'}")`);
+            _kvStoreSingleton = new UpstashRedisKVStore();
+            break;
+        }
         case 'cloudflare-kv':
         case 'cloudflare':
         default: {

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

@@ -1,5 +1,17 @@
 import { randomUUID } from 'crypto';
 import { createKVStore } from '../auth/kv-store.js';
+// ── TTL constants (seconds) ────────────────────────────────────────────────
+/** 15 minutes — matches the eBay OAuth state parameter lifetime. */
+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);
+/** 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) {
+    return new Date(Date.now() + ttlSeconds * 1_000).toISOString();
+}
 export class MultiUserAuthStore {
     kv;
     /**
@@ -36,10 +48,11 @@ export class MultiUserAuthStore {
             state,
             environment,
             createdAt: new Date().toISOString(),
+            expiresAt: secondsFromNow(OAUTH_STATE_TTL_S),
             returnTo,
             ...mcpContext,
         };
-        await this.kv.put(this.stateKey(state), record, 15 * 60);
+        await this.kv.put(this.stateKey(state), record, OAUTH_STATE_TTL_S);
         return record;
     }
     async consumeOAuthState(state) {
@@ -51,13 +64,25 @@ export class MultiUserAuthStore {
         return record;
     }
     async saveUserTokens(userId, environment, tokenData) {
+        // Derive TTL from refresh token expiry when available; fall back to 18 months.
+        let ttlSeconds = DEFAULT_REFRESH_TOKEN_TTL_S;
+        if (tokenData.userRefreshTokenExpiry) {
+            const expiryMs = typeof tokenData.userRefreshTokenExpiry === 'number'
+                ? tokenData.userRefreshTokenExpiry
+                : new Date(tokenData.userRefreshTokenExpiry).getTime();
+            const remaining = Math.floor((expiryMs - Date.now()) / 1_000);
+            if (remaining > 0) {
+                ttlSeconds = remaining;
+            }
+        }
         const record = {
             userId,
             environment,
             tokenData,
             updatedAt: new Date().toISOString(),
+            expiresAt: secondsFromNow(ttlSeconds),
         };
-        await this.kv.put(this.userTokenKey(userId, environment), record);
+        await this.kv.put(this.userTokenKey(userId, environment), record, ttlSeconds);
     }
     async getUserTokens(userId, environment) {
         return await this.kv.get(this.userTokenKey(userId, environment));
@@ -70,9 +95,10 @@ export class MultiUserAuthStore {
             userId,
             environment,
             createdAt: now,
+            expiresAt: secondsFromNow(SESSION_TTL_S),
             lastUsedAt: now,
         };
-        await this.kv.put(this.sessionKey(sessionToken), record);
+        await this.kv.put(this.sessionKey(sessionToken), record, SESSION_TTL_S);
         return record;
     }
     async getSession(sessionToken) {
@@ -91,8 +117,11 @@ export class MultiUserAuthStore {
         if (!record || record.revokedAt) {
             return;
         }
+        // Recalculate remaining TTL so Redis/KV doesn't expire an active session.
+        const expiresAt = new Date(record.expiresAt).getTime();
+        const remainingTtl = Math.max(Math.floor((expiresAt - now) / 1_000), SESSION_TTL_S);
         record.lastUsedAt = new Date(now).toISOString();
-        await this.kv.put(this.sessionKey(sessionToken), record);
+        await this.kv.put(this.sessionKey(sessionToken), record, remainingTtl);
         this.sessionTouchCache.set(sessionToken, now);
     }
     async revokeSession(sessionToken) {
@@ -100,8 +129,11 @@ export class MultiUserAuthStore {
         if (!record) {
             return;
         }
+        // Keep whatever TTL remains — just mark as revoked.
+        const expiresAt = new Date(record.expiresAt).getTime();
+        const remainingTtl = Math.max(Math.floor((expiresAt - Date.now()) / 1_000), 60);
         record.revokedAt = new Date().toISOString();
-        await this.kv.put(this.sessionKey(sessionToken), record);
+        await this.kv.put(this.sessionKey(sessionToken), record, remainingTtl);
     }
     async deleteSession(sessionToken) {
         await this.kv.delete(this.sessionKey(sessionToken));
@@ -164,8 +196,9 @@ export class MultiUserAuthStore {
             userId,
             environment,
             createdAt: new Date().toISOString(),
+            expiresAt: secondsFromNow(AUTH_CODE_TTL_S),
         };
-        await this.kv.put(`auth_code:${code}`, record, 10 * 60); // 10 min TTL
+        await this.kv.put(`auth_code:${code}`, record, AUTH_CODE_TTL_S);
         return record;
     }
     async consumeAuthCode(code) {

package/build/config/environment.js

@@ -1,4 +1,3 @@
-import { config } from 'dotenv';
 import { existsSync, readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -6,7 +5,6 @@ import { LocaleEnum } from '../types/ebay-enums.js';
 import { getVersion } from '../utils/version.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-config({ path: join(__dirname, '../../.env'), quiet: true });
 function readSecretConfigFile() {
     const configFile = process.env.EBAY_CONFIG_FILE;
     if (!configFile || !existsSync(configFile)) {
@@ -189,14 +187,34 @@ export function validateEnvironmentConfig() {
         const environment = getConfiguredEnvironment();
         const configForEnv = getSecretConfigForEnvironment(environment);
         if (!configForEnv) {
-            if (!process.env.EBAY_CLIENT_ID) {
+            // Mirror the same fallback logic used in getEbayConfig() so that
+            // per-environment overrides (EBAY_PRODUCTION_CLIENT_ID etc.) are
+            // recognised here too and don't produce false-positive errors.
+            const effectiveClientId = environment === 'production'
+                ? process.env.EBAY_PRODUCTION_CLIENT_ID || process.env.EBAY_CLIENT_ID
+                : process.env.EBAY_SANDBOX_CLIENT_ID || process.env.EBAY_CLIENT_ID;
+            const effectiveClientSecret = environment === 'production'
+                ? process.env.EBAY_PRODUCTION_CLIENT_SECRET || process.env.EBAY_CLIENT_SECRET
+                : process.env.EBAY_SANDBOX_CLIENT_SECRET || process.env.EBAY_CLIENT_SECRET;
+            // EBAY_RUNAME is the preferred name (it's a RuName string, not a URL).
+            // EBAY_REDIRECT_URI is kept for backward compatibility.
+            const effectiveRuName = environment === 'production'
+                ? process.env.EBAY_PRODUCTION_RUNAME ||
+                    process.env.EBAY_PRODUCTION_REDIRECT_URI ||
+                    process.env.EBAY_RUNAME ||
+                    process.env.EBAY_REDIRECT_URI
+                : process.env.EBAY_SANDBOX_RUNAME ||
+                    process.env.EBAY_SANDBOX_REDIRECT_URI ||
+                    process.env.EBAY_RUNAME ||
+                    process.env.EBAY_REDIRECT_URI;
+            if (!effectiveClientId) {
                 errors.push('EBAY_CLIENT_ID is not set. OAuth will not work.');
             }
-            if (!process.env.EBAY_CLIENT_SECRET) {
+            if (!effectiveClientSecret) {
                 errors.push('EBAY_CLIENT_SECRET is not set. OAuth will not work.');
             }
-            if (!process.env.EBAY_REDIRECT_URI) {
-                warnings.push('EBAY_REDIRECT_URI is not set for selected environment.');
+            if (!effectiveRuName) {
+                warnings.push('EBAY_RUNAME (or legacy EBAY_REDIRECT_URI) is not set for selected environment.');
             }
         }
     }
@@ -215,9 +233,17 @@ export function getEbayConfig(environmentOverride) {
     const fallbackClientSecret = environment === 'production'
         ? process.env.EBAY_PRODUCTION_CLIENT_SECRET || process.env.EBAY_CLIENT_SECRET || ''
         : process.env.EBAY_SANDBOX_CLIENT_SECRET || process.env.EBAY_CLIENT_SECRET || '';
+    // Preferred var is EBAY_RUNAME (clearer naming — it IS the RuName, not a URL).
+    // EBAY_REDIRECT_URI is kept for backward compatibility.
     const fallbackRedirectUri = environment === 'production'
-        ? process.env.EBAY_PRODUCTION_REDIRECT_URI || process.env.EBAY_REDIRECT_URI
-        : process.env.EBAY_SANDBOX_REDIRECT_URI || process.env.EBAY_REDIRECT_URI;
+        ? process.env.EBAY_PRODUCTION_RUNAME ||
+            process.env.EBAY_PRODUCTION_REDIRECT_URI ||
+            process.env.EBAY_RUNAME ||
+            process.env.EBAY_REDIRECT_URI
+        : process.env.EBAY_SANDBOX_RUNAME ||
+            process.env.EBAY_SANDBOX_REDIRECT_URI ||
+            process.env.EBAY_RUNAME ||
+            process.env.EBAY_REDIRECT_URI;
     return {
         clientId: secretConfig?.clientId || fallbackClientId,
         clientSecret: secretConfig?.clientSecret || fallbackClientSecret,

package/build/scripts/auto-setup.js

@@ -12,10 +12,7 @@
 import { dirname, join } from 'path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { homedir, platform } from 'os';
-import { config } from 'dotenv';
 import { fileURLToPath } from 'url';
-// Load environment variables silently
-config({ quiet: true });
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PROJECT_ROOT = join(__dirname, '../..');