@mcp-abap-adt/auth-providers 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2025-12-20
+
+### Fixed
+- **Process Termination Cleanup**: OAuth callback server now properly cleans up when process is terminated
+  - Added `process.on('exit', 'SIGTERM', 'SIGINT', 'SIGHUP')` handlers to ensure server closes on process termination
+  - This fixes port leaks when MCP clients (like Cline) kill the stdio server before authentication completes
+  - Cleanup handlers are automatically removed after authentication completes to prevent memory leaks
+  - Ports are now properly freed even when process is forcefully terminated
+
+## [0.2.1] - 2025-01-XX
+
+### Added
+- **Automatic Port Selection**: Browser auth server now automatically finds an available port if the requested port is in use
+  - When `startBrowserAuth()` is called with a port, it checks if the port is available
+  - If the port is busy, it automatically tries the next ports (up to 10 attempts)
+  - This prevents `EADDRINUSE` errors when multiple stdio servers run simultaneously
+  - Port selection happens before server startup, ensuring no conflicts
+
+### Fixed
+- **Server Port Cleanup**: Improved server shutdown to ensure ports are properly freed after authentication completes
+  - Added `keepAliveTimeout = 0` and `headersTimeout = 0` to prevent connections from staying open
+  - Added `closeAllConnections()` calls before `server.close()` to ensure all connections are closed
+  - Server now waits for HTTP response to finish before closing to prevent connection leaks
+  - Added proper error handling for browser open failures to ensure server is closed
+  - Server now properly closes in all error scenarios (timeout, browser open failure, callback errors)
+  - This prevents ports from remaining occupied after authentication completes or server shutdown
+
+### Changed
+- **Port Selection Logic**: `startBrowserAuth()` now uses `findAvailablePort()` to automatically select a free port
+  - Default behavior: tries requested port first, then tries next ports if busy
+  - Port range: tries up to 10 consecutive ports starting from the requested port
+  - Logs when a different port is used (for debugging)
+
 ## [0.2.0] - 2025-12-19
 
 ### Added

package/README.md

@@ -173,10 +173,12 @@ import { BtpTokenProvider } from '@mcp-abap-adt/auth-providers';
 import type { IAuthorizationConfig } from '@mcp-abap-adt/auth-broker';
 
 // Create provider with default port (3001)
+// The provider will automatically find an available port if 3001 is busy
 const provider = new BtpTokenProvider();
 
-// Or specify custom port for OAuth callback server (useful to avoid port conflicts)
-const providerWithCustomPort = new BtpTokenProvider(4001);
+// Or specify custom port for OAuth callback server
+// If the port is busy, the provider will automatically try the next ports
+const providerWithCustomPort = new BtpTokenProvider(4002);
 
 const authConfig: IAuthorizationConfig = {
   uaaUrl: 'https://...authentication...hana.ondemand.com',
@@ -196,7 +198,9 @@ const result = await provider.getConnectionConfig(authConfig, {
 // result.refreshToken contains refresh token (if browser flow was used)
 ```
 
-**Note**: The `browserAuthPort` parameter (default: 3001) configures the OAuth callback server port. This is useful when running the provider in environments where port 3001 is already in use (e.g., when running alongside a proxy server).
+**Note**: The `browserAuthPort` parameter (default: 3001) configures the OAuth callback server port. The provider automatically finds an available port if the requested port is in use, preventing `EADDRINUSE` errors when multiple instances run simultaneously. The server properly closes all connections and frees the port after authentication completes, ensuring no lingering port occupation. 
+
+**Process Termination Handling**: The OAuth callback server registers cleanup handlers for `SIGTERM`, `SIGINT`, `SIGHUP`, and `exit` signals. This ensures ports are properly freed even when MCP clients (like Cline) terminate the process before authentication completes. This is especially important for stdio servers where the client may kill the process at any time.
 
 ### Token Validation
 

package/dist/auth/browserAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browserAuth.d.ts","sourceRoot":"","sources":["../../src/auth/browserAuth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAyB9E;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,oBAAoB,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAa,EACnB,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,GACnB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsCzD;AAaD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE,MAAiB,EAC1B,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,GAClB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAuSzD"}
+{"version":3,"file":"browserAuth.d.ts","sourceRoot":"","sources":["../../src/auth/browserAuth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAyB9E;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,oBAAoB,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAa,EACnB,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,GACnB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsCzD;AAyCD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE,MAAiB,EAC1B,MAAM,CAAC,EAAE,OAAO,EAChB,IAAI,GAAE,MAAa,GAClB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkazD"}

package/dist/auth/browserAuth.js

@@ -42,6 +42,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.exchangeCodeForToken = exchangeCodeForToken;
 exports.startBrowserAuth = startBrowserAuth;
 const http = __importStar(require("http"));
+const net = __importStar(require("net"));
 const child_process = __importStar(require("child_process"));
 const express_1 = __importDefault(require("express"));
 const axios_1 = __importDefault(require("axios"));
@@ -111,6 +112,32 @@ function isDebugEnabled() {
         process.env.DEBUG?.includes('auth-providers') === true ||
         process.env.DEBUG?.includes('browser-auth') === true;
 }
+/**
+ * Check if a port is available
+ */
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.listen(port, () => {
+            server.once('close', () => resolve(true));
+            server.close();
+        });
+        server.on('error', () => resolve(false));
+    });
+}
+/**
+ * Find an available port starting from the given port
+ * Tries ports in range [startPort, startPort + maxAttempts)
+ */
+async function findAvailablePort(startPort, maxAttempts = 10) {
+    for (let i = 0; i < maxAttempts; i++) {
+        const port = startPort + i;
+        if (await isPortAvailable(port)) {
+            return port;
+        }
+    }
+    throw new Error(`No available port found in range ${startPort}-${startPort + maxAttempts - 1}`);
+}
 /**
  * Start browser authentication flow
  * @param authConfig Authorization configuration with UAA credentials
@@ -123,22 +150,76 @@ function isDebugEnabled() {
 async function startBrowserAuth(authConfig, browser = 'system', logger, port = 3001) {
     // Use logger if provided, otherwise null (no logging)
     const log = logger || null;
+    // Find available port (try starting from requested port, then try next ports)
+    let actualPort;
+    try {
+        actualPort = await findAvailablePort(port, 10);
+        if (actualPort !== port) {
+            log?.debug(`Port ${port} is in use, using port ${actualPort} instead`);
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to find available port starting from ${port}: ${error instanceof Error ? error.message : String(error)}`);
+    }
     return new Promise((originalResolve, originalReject) => {
         let timeoutId = null;
+        let cleanupDone = false;
+        const app = (0, express_1.default)();
+        const server = http.createServer(app);
+        // Disable keep-alive to ensure connections close immediately
+        server.keepAliveTimeout = 0;
+        server.headersTimeout = 0;
+        const PORT = actualPort;
+        let serverInstance = null;
+        // Cleanup function to ensure server is closed on process termination
+        const cleanup = () => {
+            if (cleanupDone)
+                return;
+            cleanupDone = true;
+            log?.debug(`Cleaning up OAuth callback server on port ${PORT}`);
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            if (server) {
+                try {
+                    if (typeof server.closeAllConnections === 'function') {
+                        server.closeAllConnections();
+                    }
+                    server.close(() => {
+                        log?.debug(`OAuth server closed during cleanup, port ${PORT} freed`);
+                    });
+                }
+                catch (e) {
+                    // Ignore errors during cleanup
+                }
+            }
+        };
+        // Remove cleanup listeners to prevent memory leaks
+        const removeCleanupListeners = () => {
+            process.removeListener('exit', cleanup);
+            process.removeListener('SIGTERM', cleanup);
+            process.removeListener('SIGINT', cleanup);
+            process.removeListener('SIGHUP', cleanup);
+        };
         const resolve = (value) => {
             if (timeoutId)
                 clearTimeout(timeoutId);
+            removeCleanupListeners();
             originalResolve(value);
         };
         const reject = (reason) => {
             if (timeoutId)
                 clearTimeout(timeoutId);
+            removeCleanupListeners();
             originalReject(reason);
         };
-        const app = (0, express_1.default)();
-        const server = http.createServer(app);
-        const PORT = port;
-        let serverInstance = null;
+        // Register cleanup handlers for process termination
+        // This ensures port is freed when Cline or other clients kill the process
+        process.once('exit', cleanup);
+        process.once('SIGTERM', cleanup);
+        process.once('SIGINT', cleanup);
+        process.once('SIGHUP', cleanup);
         const authorizationUrl = getJwtAuthorizationUrl(authConfig, PORT);
         // OAuth2 callback handler
         app.get('/callback', async (req, res) => {
@@ -284,36 +365,75 @@ async function startBrowserAuth(authConfig, browser = 'system', logger, port = 3
     </div>
 </body>
 </html>`;
-                // Send success page first
+                // Send success page first and ensure response is finished
                 res.send(html);
+                // Wait for response to finish before closing server
+                res.on('finish', () => {
+                    // Response finished, now we can safely close server
+                });
                 // Exchange code for tokens and close server
                 try {
                     const tokens = await exchangeCodeForToken(authConfig, code, PORT, log);
                     log?.info(`Tokens received: accessToken(${tokens.accessToken?.length || 0} chars), refreshToken(${tokens.refreshToken?.length || 0} chars)`);
-                    // Close all connections and server immediately after getting tokens
+                    // Close all connections first to ensure port is freed
                     if (typeof server.closeAllConnections === 'function') {
                         server.closeAllConnections();
                     }
-                    server.close(() => {
-                        // Server closed
-                    });
+                    // Close server after response is finished
+                    // This ensures the response connection is closed before server.close()
+                    const closeServer = () => {
+                        server.close(() => {
+                            // Server closed - port should be freed
+                            log?.debug(`Server closed, port ${PORT} should be freed`);
+                        });
+                    };
+                    if (res.finished) {
+                        // Response already finished, close immediately
+                        closeServer();
+                    }
+                    else {
+                        // Wait for response to finish
+                        res.once('finish', closeServer);
+                    }
                     resolve(tokens);
                 }
                 catch (error) {
                     if (typeof server.closeAllConnections === 'function') {
                         server.closeAllConnections();
                     }
-                    server.close(() => {
-                        // Server closed on error
-                    });
+                    // Use setTimeout to ensure connections are closed before server.close()
+                    setTimeout(() => {
+                        server.close(() => {
+                            // Server closed on error - port should be freed
+                            log?.debug(`Server closed on error, port ${PORT} should be freed`);
+                        });
+                    }, 100);
                     reject(error);
                 }
             }
             catch (error) {
                 res.status(500).send('Error processing authentication');
-                server.close(() => {
-                    // Server closed on error
-                });
+                if (typeof server.closeAllConnections === 'function') {
+                    server.closeAllConnections();
+                }
+                // Use setTimeout to ensure connections are closed before server.close()
+                setTimeout(() => {
+                    server.close(() => {
+                        // Server closed on error - port should be freed
+                        log?.debug(`Server closed on error, port ${PORT} should be freed`);
+                    });
+                }, 100);
+                reject(error);
+            }
+        });
+        // Handle server errors (e.g., EADDRINUSE)
+        server.on('error', (error) => {
+            if (error.code === 'EADDRINUSE') {
+                log?.error(`Port ${PORT} is already in use. This should not happen after port check.`);
+                reject(new Error(`Port ${PORT} is already in use. Please try again or specify a different port.`));
+            }
+            else {
+                log?.error(`Server error: ${error.message}`);
                 reject(error);
             }
         });
@@ -324,9 +444,16 @@ async function startBrowserAuth(authConfig, browser = 'system', logger, port = 3
                 // For 'none' browser, don't wait for callback - throw error immediately
                 // User must open browser manually and we can't wait for callback in automated tests
                 if (serverInstance) {
-                    server.close(() => {
-                        // Server closed
-                    });
+                    if (typeof server.closeAllConnections === 'function') {
+                        server.closeAllConnections();
+                    }
+                    // Use setTimeout to ensure connections are closed before server.close()
+                    setTimeout(() => {
+                        server.close(() => {
+                            // Server closed - port should be freed
+                            log?.debug(`Server closed (browser=none), port ${PORT} should be freed`);
+                        });
+                    }, 100);
                 }
                 reject(new Error(`Browser authentication required. Please open this URL manually: ${authorizationUrl}`));
                 return;
@@ -391,7 +518,17 @@ async function startBrowserAuth(authConfig, browser = 'system', logger, port = 3
                     }
                 }
                 catch (error) {
-                    // If browser cannot be opened, show URL and throw error for consumer to catch
+                    // If browser cannot be opened, close server and show URL
+                    if (typeof server.closeAllConnections === 'function') {
+                        server.closeAllConnections();
+                    }
+                    // Use setTimeout to ensure connections are closed before server.close()
+                    setTimeout(() => {
+                        server.close(() => {
+                            // Server closed on browser open error - port should be freed
+                            log?.debug(`Server closed on browser open error, port ${PORT} should be freed`);
+                        });
+                    }, 100);
                     log?.error(`❌ Failed to open browser: ${error?.message || String(error)}. Please open manually: ${authorizationUrl}`, { error: error?.message || String(error), url: authorizationUrl });
                     log?.info(`🔗 Open in browser: ${authorizationUrl}`, { url: authorizationUrl });
                     // Throw error so consumer can distinguish this from "service key missing" error
@@ -402,9 +539,16 @@ async function startBrowserAuth(authConfig, browser = 'system', logger, port = 3
         // Timeout after 5 minutes
         timeoutId = setTimeout(() => {
             if (serverInstance) {
-                server.close(() => {
-                    // Server closed on timeout
-                });
+                if (typeof server.closeAllConnections === 'function') {
+                    server.closeAllConnections();
+                }
+                // Use setTimeout to ensure connections are closed before server.close()
+                setTimeout(() => {
+                    server.close(() => {
+                        // Server closed on timeout - port should be freed
+                        log?.debug(`Server closed on timeout, port ${PORT} should be freed`);
+                    });
+                }, 100);
                 reject(new Error('Authentication timeout. Process aborted.'));
             }
         }, 5 * 60 * 1000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/auth-providers",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Token providers for MCP ABAP ADT auth-broker - XSUAA and BTP token providers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",