@mcp-abap-adt/auth-broker 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -11,10 +11,32 @@ Thank you to all contributors! See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the co
 
 ## [Unreleased]
 
-## [0.2.5] - 2025-01-XX
+## [0.2.7] - 2025-12-21
+
+### Added
+- **Headless Browser Mode**: Added `browser: 'headless'` option for SSH and remote sessions
+  - Logs authentication URL and waits for manual callback
+  - Ideal for environments without display (SSH, Docker, CI/CD)
+  - Differs from `'none'` which rejects immediately (for automated tests)
+
+### Changed
+- **Documentation Update**: Updated browser option documentation to clarify `headless` vs `none` modes
+
+### Dependencies
+- Updated `@mcp-abap-adt/interfaces` to `^0.2.4` for headless browser mode support
+- Updated `@mcp-abap-adt/auth-providers` to `^0.2.3` (devDependency, tests only) for headless mode implementation
+
+## [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.1` for automatic port selection and improved server shutdown
+- 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

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);
 ```
 
@@ -368,7 +368,9 @@ new AuthBroker(
   - `sessionStore` - **Required** - Store for session data. Must contain initial session with `serviceUrl`
   - `serviceKeyStore` - **Optional** - Store for service keys. Only needed for initializing sessions from service keys
   - `tokenProvider` - **Optional** - Token provider for token acquisition. Only needed for browser authentication or when direct UAA requests fail
-- `browser` - Optional browser name for authentication (`chrome`, `edge`, `firefox`, `system`, `none`). Default: `system`
+- `browser` - Optional browser name for authentication (`chrome`, `edge`, `firefox`, `system`, `headless`, `none`). Default: `system`
+  - Use `'headless'` for SSH/remote sessions - logs URL and waits for manual callback
+  - Use `'none'` for automated tests - logs URL and rejects immediately
   - For XSUAA, browser is not used (client_credentials grant type) - use `'none'`
 - `logger` - Optional logger instance. If not provided, uses no-op logger
 
@@ -456,6 +458,13 @@ try {
 - `BROWSER_AUTH_ERROR` - Browser authentication failed or cancelled (logged, throws)
 - `REFRESH_ERROR` - Token refresh failed at UAA server (logged, throws)
 
+**4. Browser Auth Disabled Errors** (when `allowBrowserAuth: false`):
+- `BROWSER_AUTH_REQUIRED` - Browser authentication is required but disabled. Thrown when:
+  - **Step 0**: No token and no UAA credentials in session, service key exists but browser auth needed
+  - **Step 2b**: Refresh token expired/invalid and browser auth needed for new token
+  - Error includes `destination` property for context
+  - Use case: Non-interactive environments (MCP stdio, Cline) where browser cannot open
+
 **Defensive Design Principles:**
 - **All external operations wrapped in try-catch**: Files may be missing/corrupted, network may fail
 - **Graceful degradation**: Store errors trigger fallback mechanisms (serviceKey → session → provider)

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,15 +30,17 @@ 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
      *               - sessionStore: Store for session data (required)
      *               - serviceKeyStore: Store for service keys (optional)
      *               - tokenProvider: Token provider implementing ITokenProvider interface (required) - handles browser-based authorization
-     * @param browser Optional browser name for authentication (chrome, edge, firefox, system, none).
+     * @param browser Optional browser name for authentication (chrome, edge, firefox, system, headless, none).
      *                Default: 'system' (system default browser).
-     *                Use 'none' to print URL instead of opening browser.
+     *                Use 'headless' for SSH/remote sessions - logs URL and waits for manual callback.
+     *                Use 'none' for automated tests - logs URL and rejects immediately.
      * @param logger Optional logger instance implementing ILogger interface. If not provided, uses no-op logger.
      */
     constructor(config: AuthBrokerConfig, browser?: string, logger?: ILogger);

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;;;;;;;;;;;OAWG;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,15 +23,17 @@ class AuthBroker {
     serviceKeyStore;
     sessionStore;
     tokenProvider;
+    allowBrowserAuth;
     /**
      * Create a new AuthBroker instance
      * @param config Configuration object with stores and token provider
      *               - sessionStore: Store for session data (required)
      *               - serviceKeyStore: Store for service keys (optional)
      *               - tokenProvider: Token provider implementing ITokenProvider interface (required) - handles browser-based authorization
-     * @param browser Optional browser name for authentication (chrome, edge, firefox, system, none).
+     * @param browser Optional browser name for authentication (chrome, edge, firefox, system, headless, none).
      *                Default: 'system' (system default browser).
-     *                Use 'none' to print URL instead of opening browser.
+     *                Use 'headless' for SSH/remote sessions - logs URL and waits for manual callback.
+     *                Use 'none' for automated tests - logs URL and rejects immediately.
      * @param logger Optional logger instance implementing ILogger interface. If not provided, uses no-op logger.
      */
     constructor(config, browser, logger) {
@@ -86,6 +88,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 +216,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 +280,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 +424,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.5",
+  "version": "0.2.7",
   "description": "JWT authentication broker for MCP ABAP ADT - manages tokens based on destination headers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,11 +51,11 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@mcp-abap-adt/interfaces": "^0.2.3",
+    "@mcp-abap-adt/interfaces": "^0.2.4",
     "axios": "^1.13.2"
   },
   "devDependencies": {
-    "@mcp-abap-adt/auth-providers": "^0.2.1",
+    "@mcp-abap-adt/auth-providers": "^0.2.3",
     "@mcp-abap-adt/auth-stores": "^0.2.5",
     "@types/express": "^5.0.5",
     "@types/jest": "^30.0.0",