@uteamup/mcp-server 1.0.0-beta.8 → 2.3.0-beta.9

package/index.js

@@ -2,7 +2,7 @@
 
 /**
  * UteamUP MCP Proxy - Production-ready OAuth handler with enhanced debugging
- * Version: 1.0.0-beta.8
+ * Version: 1.0.0-beta.9
  *
  * Features:
  * - OAuth 2.0 Authorization Code + PKCE authentication
@@ -16,13 +16,23 @@
 
 const https = require('https');
 const crypto = require('crypto');
-const { loadConfig, validateConfig, printConfigSummary } = require('./lib/config');
-const { trace, debug, info, warn, error } = require('./lib/logger');
+const { loadConfig, printConfigSummary } = require('./lib/config');
+const { trace, debug, info, error } = require('./lib/logger');
 const { startTimer, recordOAuthAttempt, recordRequest, recordCacheHit, recordCacheMiss, printMetrics } = require('./lib/metrics');
 const { retryWithBackoff } = require('./lib/retry');
+const { buildMcpForwardHeaders } = require('./lib/mcp-http-headers');
+const {
+  BoundedLineBuffer,
+  ProxyTransportError,
+  attachRequestTimeout,
+  collectResponseBody,
+  getMcpRetryLimit,
+  parseOAuthTokenResponse,
+  toPublicErrorMessage
+} = require('./lib/transport-security');
 
 // Package version
-const VERSION = '1.0.0-beta.8';
+const VERSION = '1.0.0-beta.9';
 
 // CLI argument handling
 const args = process.argv.slice(2);
@@ -48,11 +58,14 @@ ENVIRONMENT VARIABLES:
 
   Optional:
     UTEAMUP_API_BASE_URL     API endpoint (default: https://api.uteamup.com)
+    UTEAMUP_MCP_PATH         /mcp or /mcp/read-only (default: /mcp)
     UTEAMUP_LOG_LEVEL        Log level: TRACE, DEBUG, INFO, WARN, ERROR (default: INFO)
     UTEAMUP_LOG_FORMAT       Log format: text, json (default: text)
     UTEAMUP_DEBUG            Enable debug mode (1 or true) - legacy, use LOG_LEVEL instead
     UTEAMUP_REQUEST_TIMEOUT  Request timeout in ms (default: 30000)
     UTEAMUP_MAX_RETRIES      Max retry attempts (default: 3)
+    UTEAMUP_MAX_REQUEST_BYTES   Max JSON-RPC request bytes (default: 1048576)
+    UTEAMUP_MAX_RESPONSE_BYTES  Max backend response bytes (default: 10485760)
     UTEAMUP_TOKEN_CACHE_DIR  Persistent token cache directory (optional)
     UTEAMUP_TOKEN_REFRESH_MARGIN  Token refresh margin in seconds (default: 300)
 
@@ -103,7 +116,11 @@ if (args.includes('--validate-config')) {
 // Token cache
 let accessToken = null;
 let tokenExpiry = null;
+let pendingTokenRequest = null;
 let requestIdCounter = 0;
+const OAUTH_REDIRECT_URI = 'http://localhost:3000/callback';
+const STDIN_CLOSE_GRACE_MS = 2000;
+const MAX_FORWARDED_ERROR_LENGTH = 500;
 
 /**
  * Generates a unique request ID
@@ -113,6 +130,20 @@ function generateRequestId() {
   return `req_${Date.now()}_${++requestIdCounter}`;
 }
 
+/**
+ * Creates a client-safe HTTP error while preserving status for retry policy.
+ * @param {string} message
+ * @param {number|undefined} statusCode
+ * @returns {ProxyTransportError}
+ */
+function createHttpError(message, statusCode) {
+  const transportError = new ProxyTransportError(message);
+  if (Number.isInteger(statusCode)) {
+    transportError.statusCode = statusCode;
+  }
+  return transportError;
+}
+
 /**
  * Generates a PKCE (Proof Key for Code Exchange) code verifier and challenge pair.
  * @returns {{verifier: string, challenge: string}} PKCE pair with S256 challenge
@@ -130,7 +161,7 @@ function generatePKCE() {
 /**
  * Gets an OAuth access token, using cached token if still valid.
  * Implements full OAuth 2.0 Authorization Code + PKCE flow with retry logic.
- * @returns {Promise<string>} JWT access token valid for 7 days
+ * @returns {Promise<string>} JWT access token valid for the backend-reported lifetime
  * @throws {Error} If authentication fails or credentials are invalid
  */
 async function getAccessToken() {
@@ -145,6 +176,28 @@ async function getAccessToken() {
     return accessToken;
   }
 
+  // Requests run concurrently, so share one OAuth flow instead of starting one per request.
+  if (!pendingTokenRequest) {
+    pendingTokenRequest = requestNewAccessToken().finally(() => {
+      pendingTokenRequest = null;
+    });
+  }
+  return pendingTokenRequest;
+}
+
+/**
+ * Drops the cached token after the backend rejected it, unless a newer token
+ * has already replaced it.
+ * @param {string} rejectedToken
+ */
+function clearAccessToken(rejectedToken) {
+  if (accessToken === rejectedToken) {
+    accessToken = null;
+    tokenExpiry = null;
+  }
+}
+
+async function requestNewAccessToken() {
   recordCacheMiss();
   info('Getting new access token');
 
@@ -160,41 +213,63 @@ async function getAccessToken() {
           const authParams = new URLSearchParams({
             response_type: 'code',
             client_id: config.apiKey,
-            redirect_uri: 'http://localhost:3000/callback',
+            redirect_uri: OAUTH_REDIRECT_URI,
             code_challenge: challenge,
             code_challenge_method: 'S256',
             scope: 'mcp:full'
           });
 
-          trace('Requesting authorization code', {
-            clientId: config.apiKey.substring(0, 8) + '...',
-            scope: 'mcp:full'
-          });
+          trace('Requesting authorization code', { scope: 'mcp:full' });
 
-          https.get(`${config.baseUrl}/oauth/authorize?${authParams}`, {
-            rejectUnauthorized: false, // Allow self-signed certs for dev
+          const authorizeUrl = new URL('/oauth/authorize', config.baseUrl);
+          authorizeUrl.search = authParams.toString();
+          const authRequest = https.get(authorizeUrl, {
+            // UTEAMUP-SEC-2026-05-02-008: TLS verification is on by default;
+            // UTEAMUP_INSECURE_TLS=1 opts in for self-signed dev certs.
+            // Production host (api.uteamup.com) ignores the flag.
+            rejectUnauthorized: !config.insecureTLS,
             timeout: config.requestTimeout
           }, (res) => {
             const location = res.headers.location || '';
-            debug('Authorization redirect received', { location });
+            res.resume();
+            debug('Authorization redirect received', {
+              statusCode: res.statusCode,
+              hasLocation: Boolean(location)
+            });
+
+            let redirectUrl;
+            try {
+              redirectUrl = new URL(location, OAUTH_REDIRECT_URI);
+            } catch {
+              reject(new ProxyTransportError('OAuth authorization returned an invalid redirect'));
+              return;
+            }
+
+            const expectedRedirect = new URL(OAUTH_REDIRECT_URI);
+            if (
+              redirectUrl.origin !== expectedRedirect.origin ||
+              redirectUrl.pathname !== expectedRedirect.pathname
+            ) {
+              reject(new ProxyTransportError('OAuth authorization returned an unexpected redirect'));
+              return;
+            }
 
             // Check for OAuth error in redirect
-            if (location.includes('error=')) {
-              const url = new URL(location, 'http://localhost');
-              const errorType = url.searchParams.get('error');
-              const description = url.searchParams.get('error_description');
-              reject(new Error(`OAuth authorization failed: ${errorType} - ${description || 'Unknown error'}`));
+            if (redirectUrl.searchParams.has('error')) {
+              reject(new ProxyTransportError('OAuth authorization was denied'));
               return;
             }
 
-            const match = location.match(/code=([^&]+)/);
-            if (match) {
+            const authorizationCode = redirectUrl.searchParams.get('code');
+            if (authorizationCode) {
               debug('Authorization code received');
-              resolve(match[1]);
+              resolve(authorizationCode);
             } else {
-              reject(new Error('No authorization code in redirect. Location: ' + location));
+              reject(new ProxyTransportError('OAuth authorization did not return a code'));
             }
-          }).on('error', reject);
+          });
+          authRequest.once('error', reject);
+          attachRequestTimeout(authRequest, 'OAuth authorization request');
         });
       },
       {
@@ -203,79 +278,64 @@ async function getAccessToken() {
       }
     );
 
-    info('Authorization code received', {
-      codePrefix: authCode.substring(0, 20) + '...'
-    });
+    info('Authorization code received');
 
     // Step 2: Exchange for access token with retry
     const tokenData = new URLSearchParams({
       grant_type: 'authorization_code',
       code: authCode,
-      redirect_uri: 'http://localhost:3000/callback',
+      redirect_uri: OAUTH_REDIRECT_URI,
       client_id: config.apiKey,
       client_secret: config.secret,
       code_verifier: verifier
     }).toString();
 
-    const token = await retryWithBackoff(
+    const tokenResponse = await retryWithBackoff(
       async () => {
         return new Promise((resolve, reject) => {
           trace('Exchanging authorization code for access token');
 
-          const req = https.request(`${config.baseUrl}/oauth/token`, {
+          const req = https.request(new URL('/oauth/token', config.baseUrl), {
             method: 'POST',
             headers: {
               'Content-Type': 'application/x-www-form-urlencoded',
               'Content-Length': Buffer.byteLength(tokenData)
             },
-            rejectUnauthorized: false,
+            // UTEAMUP-SEC-2026-05-02-008: see authorize handler above.
+            rejectUnauthorized: !config.insecureTLS,
             timeout: config.requestTimeout
-          }, (res) => {
-            let data = '';
-            res.on('data', chunk => data += chunk);
-            res.on('end', () => {
+          }, async (res) => {
+            try {
+              const data = await collectResponseBody(res, config.maxResponseBytes, 'OAuth token response');
               debug('Token exchange response received', {
                 statusCode: res.statusCode,
-                dataLength: data.length
+                dataLength: Buffer.byteLength(data)
               });
 
               // Check for error status codes
               if (res.statusCode === 401) {
-                reject(new Error('Authentication failed: Invalid API Key or Secret. Please verify your credentials in UteamUP Tenant Settings → API Keys.'));
+                reject(createHttpError('Authentication failed: verify the configured API credentials', res.statusCode));
                 return;
               }
               if (res.statusCode === 403) {
-                if (data.includes('MCP') || data.includes('mcp')) {
-                  reject(new Error('MCP access denied: Your API key does not have MCP enabled. Create a new MCP-enabled key in Tenant Settings → API Keys.'));
-                } else {
-                  reject(new Error('Access forbidden: ' + data));
-                }
+                reject(createHttpError('MCP access denied for the configured API credentials', res.statusCode));
                 return;
               }
               if (res.statusCode !== 200) {
-                reject(new Error(`Token exchange failed (HTTP ${res.statusCode}): ${data}`));
+                reject(createHttpError(`Token exchange failed (HTTP ${res.statusCode})`, res.statusCode));
                 return;
               }
 
-              try {
-                const json = JSON.parse(data);
-                // Accept both camelCase (accessToken) and snake_case (access_token) formats
-                const token = json.accessToken || json.access_token;
-                if (token) {
-                  debug('Access token received successfully');
-                  resolve(token);
-                } else if (json.error) {
-                  reject(new Error(`OAuth error: ${json.error} - ${json.error_description || ''}`));
-                } else {
-                  reject(new Error(`Token exchange failed: ${data}`));
-                }
-              } catch (e) {
-                reject(new Error(`Invalid JSON response: ${data}`));
-              }
-            });
+              const parsedToken = parseOAuthTokenResponse(data);
+              debug('Access token received successfully');
+              resolve(parsedToken);
+            } catch (responseError) {
+              reject(responseError);
+            }
           });
 
-          req.on('error', reject);
+          req.once('error', reject);
+          attachRequestTimeout(req, 'OAuth token request');
           req.write(tokenData);
           req.end();
         });
@@ -286,8 +346,8 @@ async function getAccessToken() {
       }
     );
 
-    accessToken = token;
-    tokenExpiry = Date.now() + (7 * 24 * 60 * 60 * 1000); // 7 days
+    accessToken = tokenResponse.accessToken;
+    tokenExpiry = Date.now() + (tokenResponse.expiresInSeconds * 1000);
 
     const duration = stopTimer();
     recordOAuthAttempt(true, duration);
@@ -301,7 +361,11 @@ async function getAccessToken() {
   } catch (err) {
     const duration = stopTimer();
     recordOAuthAttempt(false, duration);
-    error('OAuth flow failed', err);
+    error('OAuth flow failed', {
+      errorType: err?.name,
+      errorCode: err?.code,
+      statusCode: err?.statusCode
+    });
     throw err;
   }
 }
@@ -329,8 +393,8 @@ function parseSSE(sseData) {
   if (jsonData) {
     try {
       return JSON.parse(jsonData);
-    } catch (e) {
-      debug('SSE data parse error', { error: e.message });
+    } catch {
+      debug('SSE data parse error');
       return null;
     }
   }
@@ -338,9 +402,169 @@ function parseSSE(sseData) {
   return null;
 }
 
+/**
+ * Builds the error for a failed backend HTTP response. Keeps the backend's own
+ * JSON-RPC error or ProblemDetails message so the client sees why the call failed.
+ * @param {number} statusCode
+ * @param {string} responseData
+ * @returns {ProxyTransportError} error with statusCode, plus jsonRpcError when the backend sent one
+ */
+function createBackendHttpError(statusCode, responseData) {
+  let body = parseSSE(responseData);
+  if (!body) {
+    try {
+      body = JSON.parse(responseData);
+    } catch {
+      body = null;
+    }
+  }
+
+  const rpcError = body?.error;
+  if (rpcError && Number.isInteger(rpcError.code) && typeof rpcError.message === 'string') {
+    const transportError = createHttpError(rpcError.message, statusCode);
+    transportError.jsonRpcError = rpcError;
+    return transportError;
+  }
+
+  const detail = [body?.detail, body?.title, body?.message]
+    .find(value => typeof value === 'string' && value.trim().length > 0);
+  if (detail) {
+    return createHttpError(
+      `MCP request failed (HTTP ${statusCode}): ${detail.trim().slice(0, MAX_FORWARDED_ERROR_LENGTH)}`,
+      statusCode
+    );
+  }
+
+  return createHttpError(`MCP request failed (HTTP ${statusCode})`, statusCode);
+}
+
+/**
+ * Posts one JSON-RPC message to the backend /mcp endpoint with the given token.
+ * Each attempt has a total deadline: the socket `timeout` only fires on an idle
+ * socket, so a backend that keeps sending bytes (e.g. SSE keepalives) would
+ * otherwise hold the request open forever.
+ * @param {object} request - JSON-RPC 2.0 request object
+ * @param {string} requestId - Unique request ID for tracing
+ * @param {string} data - Serialized request body
+ * @param {string} token - OAuth access token
+ * @returns {Promise<object|null>} JSON-RPC 2.0 response object, or null for an acknowledged notification
+ */
+function postToBackend(request, requestId, data, token) {
+  return retryWithBackoff(
+    async () => {
+      return new Promise((resolvePromise, rejectPromise) => {
+        let deadline;
+        const resolve = value => {
+          clearTimeout(deadline);
+          resolvePromise(value);
+        };
+        const reject = err => {
+          clearTimeout(deadline);
+          rejectPromise(err);
+        };
+
+        const req = https.request(new URL(config.mcpPath, config.baseUrl), {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json, text/event-stream',
+            'Content-Length': Buffer.byteLength(data),
+            'X-Request-ID': requestId,
+            ...buildMcpForwardHeaders(request)
+          },
+          // UTEAMUP-SEC-2026-05-02-008: see authorize handler above.
+          rejectUnauthorized: !config.insecureTLS,
+          timeout: config.requestTimeout
+        }, async (res) => {
+          try {
+            const responseData = await collectResponseBody(res, config.maxResponseBytes, 'MCP response');
+            trace('MCP response received', {
+              requestId,
+              statusCode: res.statusCode,
+              dataLength: Buffer.byteLength(responseData)
+            });
+
+            if (res.statusCode >= 400) {
+              reject(createBackendHttpError(res.statusCode, responseData));
+              return;
+            }
+
+            // Handle empty responses (e.g., HTTP 202 for notifications)
+            if (responseData.length === 0) {
+              if (request.id === undefined || request.id === null) {
+                trace('Notification acknowledged, no response needed', { requestId });
+                resolve(null);
+              } else {
+                debug('Empty response received for a request', { requestId });
+                resolve({
+                  jsonrpc: '2.0',
+                  error: { code: -32603, message: 'Backend returned an empty response' },
+                  id: request.id
+                });
+              }
+              return;
+            }
+
+            // Try parsing as SSE format first (text/event-stream)
+            if (responseData.includes('event:') || responseData.includes('data:')) {
+              debug('Detected SSE format, parsing...', { requestId });
+              const parsed = parseSSE(responseData);
+              if (parsed) {
+                trace('SSE parsed successfully', {
+                  requestId,
+                  responseId: parsed?.id,
+                  hasError: Boolean(parsed?.error)
+                });
+                resolve(parsed);
+                return;
+              }
+            }
+
+            // Fall back to plain JSON parsing
+            try {
+              const parsed = JSON.parse(responseData);
+              trace('JSON parsed successfully', {
+                requestId,
+                responseId: parsed?.id,
+                hasError: Boolean(parsed?.error)
+              });
+              resolve(parsed);
+            } catch {
+              debug('Parse error (not SSE, not JSON)', { requestId });
+              resolve({
+                jsonrpc: '2.0',
+                error: { code: -32700, message: 'Backend returned an invalid response' },
+                id: request.id
+              });
+            }
+          } catch (responseError) {
+            reject(responseError);
+          }
+        });
+
+        req.once('error', reject);
+        attachRequestTimeout(req, 'MCP request');
+        deadline = setTimeout(() => {
+          reject(new ProxyTransportError(`Backend did not answer within ${config.requestTimeout} ms`));
+          req.destroy();
+        }, config.requestTimeout);
+        req.write(data);
+        req.end();
+      });
+    },
+    {
+      maxRetries: getMcpRetryLimit(request.method, config.maxRetries),
+      operationName: `MCP request [${request.method}]`
+    }
+  );
+}
+
 /**
  * Forwards a JSON-RPC 2.0 MCP request to the backend.
  * Handles both plain JSON and Server-Sent Events (SSE) response formats.
+ * A 401 means the backend rejected the token before running anything, so the
+ * request is replayed once with a fresh token (safe even for tools/call).
  * @param {object} request - JSON-RPC 2.0 request object
  * @param {string} requestId - Unique request ID for tracing
  * @returns {Promise<object>} JSON-RPC 2.0 response object
@@ -349,91 +573,37 @@ async function forwardRequest(request, requestId) {
   const stopTimer = startTimer(`request_${request.method}`);
 
   try {
-    const token = await getAccessToken();
     const data = JSON.stringify(request);
+    const requestBytes = Buffer.byteLength(data);
+    if (requestBytes > config.maxRequestBytes) {
+      throw new ProxyTransportError('Request exceeds the configured size limit');
+    }
 
     trace('Forwarding MCP request', {
       requestId,
       method: request.method,
       id: request.id,
-      bodyLength: data.length
+      bodyLength: requestBytes
     });
 
-    const response = await retryWithBackoff(
-      async () => {
-        return new Promise((resolve, reject) => {
-          const req = https.request(`${config.baseUrl}/mcp`, {
-            method: 'POST',
-            headers: {
-              'Authorization': `Bearer ${token}`,
-              'Content-Type': 'application/json',
-              'Accept': 'application/json, text/event-stream',
-              'Content-Length': Buffer.byteLength(data),
-              'X-Request-ID': requestId
-            },
-            rejectUnauthorized: false,
-            timeout: config.requestTimeout
-          }, (res) => {
-            let responseData = '';
-            res.on('data', chunk => responseData += chunk);
-            res.on('end', () => {
-              trace('MCP response received', {
-                requestId,
-                statusCode: res.statusCode,
-                dataLength: responseData.length
-              });
-
-              // Handle empty responses (e.g., HTTP 202 for notifications)
-              if (responseData.length === 0) {
-                debug('Empty response received (likely notification acknowledged)', { requestId });
-                // For notifications (no id), don't send a response
-                if (request.id === undefined || request.id === null) {
-                  trace('Notification acknowledged, no response needed', { requestId });
-                  resolve(null); // Don't send anything back for notifications
-                } else {
-                  // For requests with ID, return success
-                  resolve({ jsonrpc: '2.0', result: {}, id: request.id });
-                }
-                return;
-              }
-
-              // Try parsing as SSE format first (text/event-stream)
-              if (responseData.includes('event:') || responseData.includes('data:')) {
-                debug('Detected SSE format, parsing...', { requestId });
-                const parsed = parseSSE(responseData);
-                if (parsed) {
-                  trace('SSE parsed successfully', { requestId, result: parsed });
-                  resolve(parsed);
-                  return;
-                }
-              }
-
-              // Fall back to plain JSON parsing
-              try {
-                const parsed = JSON.parse(responseData);
-                trace('JSON parsed successfully', { requestId, result: parsed });
-                resolve(parsed);
-              } catch (e) {
-                debug('Parse error (not SSE, not JSON)', { requestId, error: e.message });
-                resolve({
-                  jsonrpc: '2.0',
-                  error: { code: -32700, message: 'Parse error', data: responseData },
-                  id: request.id
-                });
-              }
-            });
-          });
+    let token = await getAccessToken();
+    let response;
+    try {
+      response = await postToBackend(request, requestId, data, token);
+    } catch (err) {
+      if (err?.statusCode !== 401) throw err;
 
-          req.on('error', reject);
-          req.write(data);
-          req.end();
-        });
-      },
-      {
-        maxRetries: config.maxRetries,
-        operationName: `MCP request [${request.method}]`
+      info('Backend rejected the access token, re-authenticating once', { requestId });
+      clearAccessToken(token);
+      token = await getAccessToken();
+      try {
+        response = await postToBackend(request, requestId, data, token);
+      } catch (retryErr) {
+        if (retryErr?.statusCode !== 401) throw retryErr;
+        clearAccessToken(token);
+        throw createHttpError('Authentication failed: the backend rejected the access token', 401);
       }
-    );
+    }
 
     const duration = stopTimer();
     recordRequest(true, duration, request.method);
@@ -445,7 +615,9 @@ async function forwardRequest(request, requestId) {
     error('Request forwarding failed', {
       requestId,
       method: request.method,
-      error: err.message
+      errorType: err?.name,
+      errorCode: err?.code,
+      statusCode: err?.statusCode
     });
     throw err;
   }
@@ -460,20 +632,19 @@ if (args.includes('--test-auth')) {
 
     try {
       const stopTimer = startTimer('test_auth');
-      const token = await getAccessToken();
+      await getAccessToken();
       const duration = stopTimer();
 
       console.error('');
       console.error('✅ Authentication successful!');
       console.error(`   Token obtained in ${duration}ms`);
-      console.error(`   Token prefix: ${token.substring(0, 20)}...`);
       console.error(`   Token expires: ${new Date(tokenExpiry).toISOString()}`);
       printMetrics();
       process.exit(0);
     } catch (err) {
       console.error('');
       console.error('❌ Authentication failed!');
-      console.error(`   Error: ${err.message}`);
+      console.error(`   Error: ${toPublicErrorMessage(err)}`);
       process.exit(1);
     }
   })();
@@ -491,79 +662,123 @@ async function main() {
 
   printConfigSummary(config);
 
-  let buffer = '';
-
-  process.stdin.on('data', async (chunk) => {
-    buffer += chunk.toString();
-
-    let newlineIndex;
-    while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
-      const line = buffer.slice(0, newlineIndex).trim();
-      buffer = buffer.slice(newlineIndex + 1);
+  const lineBuffer = new BoundedLineBuffer(config.maxRequestBytes);
+  // Requests run concurrently so one slow tools/call cannot block the rest.
+  // Each response is one stdout.write call, so messages never interleave.
+  const inFlight = new Set();
+
+  const writeErrorResponse = (code, message, id = null) => {
+    process.stdout.write(JSON.stringify({
+      jsonrpc: '2.0',
+      error: { code, message },
+      id
+    }) + '\n');
+  };
+
+  const processInputEvent = async inputEvent => {
+    if (inputEvent.oversized) {
+      writeErrorResponse(-32600, 'Request exceeds the configured size limit');
+      return;
+    }
 
-      if (!line) continue;
+    const line = inputEvent.line.trim();
+    if (!line) return;
 
-      const requestId = generateRequestId();
+    const requestId = generateRequestId();
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      writeErrorResponse(-32700, 'Parse error');
+      return;
+    }
 
-      try {
-        const request = JSON.parse(line);
+    if (
+      request === null ||
+      Array.isArray(request) ||
+      typeof request !== 'object' ||
+      request.jsonrpc !== '2.0' ||
+      typeof request.method !== 'string' ||
+      request.method.length === 0
+    ) {
+      writeErrorResponse(-32600, 'Invalid Request', request?.id ?? null);
+      return;
+    }
 
-        info('Processing request', {
-          requestId,
-          method: request.method,
-          id: request.id
-        });
+    // Liveness check of this proxy: needs neither a token nor the backend.
+    if (request.method === 'ping') {
+      if (request.id !== undefined && request.id !== null) {
+        process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: request.id, result: {} }) + '\n');
+      }
+      return;
+    }
 
-        const response = await forwardRequest(request, requestId);
-
-        // For notifications (null response), don't write anything to stdout
-        if (response === null) {
-          debug('Notification handled, no response sent', { requestId });
-          continue;
-        }
-
-        // Ensure response includes request ID for proper JSON-RPC 2.0 format
-        if (request.id !== undefined && response.id === undefined) {
-          response.id = request.id;
-        }
-
-        process.stdout.write(JSON.stringify(response) + '\n');
-        trace('Response sent', { requestId, responseId: request.id });
-      } catch (err) {
-        error('Request processing error', {
-          requestId,
-          error: err.message
-        });
+    try {
+      info('Processing request', {
+        requestId,
+        method: request.method,
+        id: request.id
+      });
+
+      const response = await forwardRequest(request, requestId);
+
+      // For notifications (null response), don't write anything to stdout.
+      if (response === null) {
+        debug('Notification handled, no response sent', { requestId });
+        return;
+      }
 
-        // Try to extract request ID if possible
-        let requestIdFromLine = null;
-        try {
-          const req = JSON.parse(line);
-          requestIdFromLine = req.id;
-        } catch (e) {
-          // Line wasn't valid JSON, use null
-        }
+      // Ensure response includes request ID for proper JSON-RPC 2.0 format.
+      if (request.id !== undefined && response.id === undefined) {
+        response.id = request.id;
+      }
 
-        const errorResponse = {
+      process.stdout.write(JSON.stringify(response) + '\n');
+      trace('Response sent', { requestId, responseId: request.id });
+    } catch (err) {
+      error('Request processing error', {
+        requestId,
+        errorType: err?.name,
+        errorCode: err?.code,
+        statusCode: err?.statusCode
+      });
+
+      if (err?.jsonRpcError) {
+        process.stdout.write(JSON.stringify({
           jsonrpc: '2.0',
-          error: {
-            code: -32603,
-            message: err.message,
-            data: config.logLevel === 'DEBUG' || config.logLevel === 'TRACE' ? err.stack : undefined
-          },
-          id: requestIdFromLine
-        };
-        process.stdout.write(JSON.stringify(errorResponse) + '\n');
+          error: err.jsonRpcError,
+          id: request.id ?? null
+        }) + '\n');
+      } else {
+        writeErrorResponse(-32603, toPublicErrorMessage(err), request.id ?? null);
       }
     }
-  });
+  };
 
-  process.stdin.on('end', () => {
-    info('stdin closed, exiting');
-    printMetrics();
-    process.exit(0);
+  process.stdin.on('data', chunk => {
+    for (const inputEvent of lineBuffer.push(chunk)) {
+      const task = processInputEvent(inputEvent).finally(() => inFlight.delete(task));
+      inFlight.add(task);
+    }
   });
 
+  // The client closing stdin means it is gone (e.g. a reconnect started a new
+  // proxy). Give in-flight requests a short grace period, then exit even if one
+  // is stuck, so this process never outlives its client.
+  let exiting = false;
+  const exitAfterInFlight = () => {
+    if (exiting) return;
+    exiting = true;
+    info('stdin closed, exiting', { inFlight: inFlight.size, graceMs: STDIN_CLOSE_GRACE_MS });
+    const grace = new Promise(resolve => setTimeout(resolve, STDIN_CLOSE_GRACE_MS));
+    Promise.race([Promise.allSettled([...inFlight]), grace]).then(() => {
+      printMetrics();
+      process.exit(0);
+    });
+  };
+  process.stdin.on('end', exitAfterInFlight);
+  process.stdin.on('close', exitAfterInFlight);
+
   process.stdin.resume();
 }
 
@@ -581,11 +796,17 @@ process.on('SIGTERM', () => {
 });
 
 process.on('uncaughtException', (err) => {
-  error('Uncaught exception', err);
+  error('Uncaught exception', {
+    errorType: err?.name,
+    errorCode: err?.code
+  });
   process.exit(1);
 });
 
 main().catch((err) => {
-  error('Fatal error', err);
+  error('Fatal error', {
+    errorType: err?.name,
+    errorCode: err?.code
+  });
   process.exit(1);
 });