@mcp-abap-adt/auth-broker 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -11,6 +11,22 @@ Thank you to all contributors! See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the co
 
 ## [Unreleased]
 
+## [0.2.5] - 2025-12-20
+
+### Added
+- **`allowBrowserAuth` Option**: New configuration option to control browser-based authentication
+  - When `allowBrowserAuth: false`, broker throws `BROWSER_AUTH_REQUIRED` error instead of blocking on browser auth
+  - Useful for headless/non-interactive environments (e.g., MCP stdio transport with Cline)
+  - Error includes `code: 'BROWSER_AUTH_REQUIRED'` and `destination` property for programmatic handling
+  - Broker still works with valid session tokens or refresh tokens when browser auth is disabled
+
+### Dependencies
+- Updated `@mcp-abap-adt/auth-providers` to `^0.2.2` for automatic port selection, improved server shutdown, and process termination cleanup
+  - Browser auth server now automatically finds an available port if the requested port is in use
+  - Improved server shutdown ensures ports are properly freed after authentication completes
+  - Prevents `EADDRINUSE` errors when multiple stdio servers run simultaneously
+  - Ports are properly released after server shutdown, preventing lingering port occupation
+
 ## [0.2.4] - 2025-12-19
 
 ### Changed

package/README.md

@@ -53,12 +53,12 @@ const broker = new AuthBroker({
   tokenProvider: new BtpTokenProvider(), // optional
 }, 'chrome', logger);
 
-// Disable direct client_credentials (force provider/browser flow, e.g., for ABAP ADT)
-const brokerNoClientCreds = new AuthBroker({
+// Disable browser authentication for headless/stdio environments (e.g., MCP with Cline)
+const brokerNoBrowser = new AuthBroker({
   sessionStore: new AbapSessionStore('/path/to/destinations'),
   serviceKeyStore: new AbapServiceKeyStore('/path/to/destinations'),
   tokenProvider: new BtpTokenProvider(),
-  allowClientCredentials: false,
+  allowBrowserAuth: false, // Throws BROWSER_AUTH_REQUIRED if browser auth needed
 }, 'chrome', logger);
 ```
 
@@ -98,6 +98,8 @@ const broker = new AuthBroker({
 }, 'chrome');
 ```
 
+**Note**: The `BtpTokenProvider` automatically finds an available port if the requested port is in use. This prevents `EADDRINUSE` errors when multiple stdio servers run simultaneously. The server properly closes all connections and frees the port after authentication completes, ensuring no lingering port occupation.
+
 ### Getting Tokens
 
 ```typescript
@@ -496,6 +498,8 @@ The package uses `ITokenProvider` interface for token acquisition. Two implement
 
 - **`BtpTokenProvider`** - For BTP/ABAP authentication (full scope)
   - Constructor accepts optional `browserAuthPort?: number` parameter (default: 3001)
+  - Automatically finds an available port if the requested port is in use (prevents `EADDRINUSE` errors)
+  - Server properly closes all connections and frees the port after authentication completes
   - Use custom port to avoid conflicts when running alongside other services (e.g., proxy server)
   - Uses browser-based OAuth2 flow (if no refresh token)
   - Uses refresh token if available

package/dist/AuthBroker.d.ts

@@ -14,6 +14,12 @@ export interface AuthBrokerConfig {
     serviceKeyStore?: IServiceKeyStore;
     /** Token provider (required) - handles token refresh and authentication flows through browser-based authorization (e.g., XSUAA provider) */
     tokenProvider: ITokenProvider;
+    /**
+     * Allow browser-based authentication (optional, default: true)
+     * When false, getToken() will throw BROWSER_AUTH_REQUIRED error instead of blocking on browser auth.
+     * Use this for headless/non-interactive environments (e.g., MCP stdio transport).
+     */
+    allowBrowserAuth?: boolean;
 }
 /**
  * AuthBroker manages JWT authentication tokens for destinations
@@ -24,6 +30,7 @@ export declare class AuthBroker {
     private serviceKeyStore;
     private sessionStore;
     private tokenProvider;
+    private allowBrowserAuth;
     /**
      * Create a new AuthBroker instance
      * @param config Configuration object with stores and token provider

package/dist/AuthBroker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAA8C,MAAM,0BAA0B,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC/G,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAa7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,YAAY,EAAE,aAAa,CAAC;IAC5B,uEAAuE;IACvE,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,4IAA4I;IAC5I,aAAa,EAAE,cAAc,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAiB;IAEtC;;;;;;;;;;OAUG;gBAED,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,OAAO;IAsElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkWpD;;;;;OAKG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOxD;;;;OAIG;IACG,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4CvF;;;;OAIG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CA0ClF"}
+{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAA8C,MAAM,0BAA0B,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC/G,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAa7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,YAAY,EAAE,aAAa,CAAC;IAC5B,uEAAuE;IACvE,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,4IAA4I;IAC5I,aAAa,EAAE,cAAc,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,gBAAgB,CAAU;IAElC;;;;;;;;;;OAUG;gBAED,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,OAAO;IAuElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgYpD;;;;;OAKG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOxD;;;;OAIG;IACG,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4CvF;;;;OAIG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CA0ClF"}

package/dist/AuthBroker.js

@@ -23,6 +23,7 @@ class AuthBroker {
     serviceKeyStore;
     sessionStore;
     tokenProvider;
+    allowBrowserAuth;
     /**
      * Create a new AuthBroker instance
      * @param config Configuration object with stores and token provider
@@ -86,6 +87,7 @@ class AuthBroker {
         this.tokenProvider = tokenProvider;
         this.browser = browser || 'system';
         this.logger = logger || noOpLogger;
+        this.allowBrowserAuth = config.allowBrowserAuth ?? true;
         // Log successful initialization
         const hasServiceKeyStore = !!this.serviceKeyStore;
         this.logger?.debug(`AuthBroker initialized: sessionStore(ok), serviceKeyStore(${hasServiceKeyStore ? 'ok' : 'none'}), tokenProvider(ok)`);
@@ -213,6 +215,15 @@ class AuthBroker {
                     this.logger?.error(`Step 0: Service key for ${destination} missing UAA credentials`);
                     throw new Error(`Service key for destination "${destination}" does not contain UAA credentials`);
                 }
+                // Check if browser auth is allowed
+                if (!this.allowBrowserAuth) {
+                    const error = new Error(`Browser authentication required for destination "${destination}" but allowBrowserAuth is disabled. ` +
+                        `Either enable browser auth or provide a valid session with token.`);
+                    error.code = 'BROWSER_AUTH_REQUIRED';
+                    error.destination = destination;
+                    this.logger?.error(`Step 0: Browser auth required but disabled for ${destination}`);
+                    throw error;
+                }
                 // Use tokenProvider for browser-based authentication
                 this.logger?.debug(`Step 0: Authenticating via provider (browser) for ${destination} using service key UAA credentials`);
                 let tokenResult;
@@ -268,6 +279,10 @@ class AuthBroker {
                 return tokenResult.connectionConfig.authorizationToken;
             }
             catch (error) {
+                // Re-throw BROWSER_AUTH_REQUIRED error without wrapping
+                if (error.code === 'BROWSER_AUTH_REQUIRED') {
+                    throw error;
+                }
                 // Handle typed store errors
                 if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
                     this.logger?.error(`Step 0: Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
@@ -408,6 +423,16 @@ class AuthBroker {
             this.logger?.debug(`Step 2a: No refresh token in session for ${destination}, skipping to service key refresh`);
         }
         // Try refresh from service key (browser authentication)
+        // Check if browser auth is allowed
+        if (!this.allowBrowserAuth) {
+            const error = new Error(`Browser authentication required for destination "${destination}" but allowBrowserAuth is disabled. ` +
+                `Token refresh via session failed and browser auth is not allowed. ` +
+                `Either enable browser auth or ensure a valid refresh token exists in session.`);
+            error.code = 'BROWSER_AUTH_REQUIRED';
+            error.destination = destination;
+            this.logger?.error(`Step 2b: Browser auth required but disabled for ${destination}`);
+            throw error;
+        }
         try {
             this.logger?.debug(`Step 2b: Trying refreshTokenFromServiceKey for ${destination}`);
             const tokenResult = await this.tokenProvider.refreshTokenFromServiceKey(uaaCredentials, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/auth-broker",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "JWT authentication broker for MCP ABAP ADT - manages tokens based on destination headers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,7 +55,7 @@
     "axios": "^1.13.2"
   },
   "devDependencies": {
-    "@mcp-abap-adt/auth-providers": "^0.2.0",
+    "@mcp-abap-adt/auth-providers": "^0.2.2",
     "@mcp-abap-adt/auth-stores": "^0.2.5",
     "@types/express": "^5.0.5",
     "@types/jest": "^30.0.0",