@mcp-abap-adt/auth-providers 0.1.5 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **Typed Error Classes**: Added specialized error classes for better error handling and debugging
+  - `TokenProviderError` - Base class for all token provider errors with error code
+  - `ValidationError` - Thrown when authConfig validation fails (includes `missingFields: string[]` array)
+  - `RefreshError` - Thrown when token refresh operation fails (includes `cause?: Error` with original error)
+  - `SessionDataError` - Thrown when session data is invalid or incomplete (includes `missingFields` array)
+  - `ServiceKeyError` - Thrown when service key data is invalid or incomplete (includes `missingFields` array)
+  - `BrowserAuthError` - Thrown when browser authentication fails or is cancelled (includes `cause` error)
+  - All error codes use constants from `@mcp-abap-adt/interfaces` package (`TOKEN_PROVIDER_ERROR_CODES`)
+  - Errors are exported from package root for easy import
+
+### Changed
+- **Enhanced Validation Error Messages**: Validation errors now list specific missing field names instead of generic messages
+  - Example: `XSUAA refreshTokenFromSession: authConfig missing required fields: uaaUrl, uaaClientId`
+  - `ValidationError` includes `missingFields: string[]` property for programmatic access to missing fields
+  - Each missing field is checked individually and added to the list
+- **Improved Error Handling in Refresh Methods**: All refresh operations now wrap errors with typed error classes
+  - `refreshTokenFromSession` throws `RefreshError` when client_credentials or browser auth fails
+  - `refreshTokenFromServiceKey` throws `RefreshError` when browser authentication fails
+  - Original error is preserved in `RefreshError.cause` property for debugging
+  - Error messages include provider type (XSUAA/BTP) and operation name for clarity
+- **Dependency Update**: Updated `@mcp-abap-adt/interfaces` to `^0.2.2` for `TOKEN_PROVIDER_ERROR_CODES` constants
+- **Test Coverage**: Added tests for error handling edge cases
+  - Tests verify `RefreshError` is thrown when authentication fails
+  - Tests verify `ValidationError` includes correct missing field names
+  - Tests verify error messages contain expected substrings
+
 ## [0.1.5] - 2025-12-13
 
 ### Changed

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,7 @@ 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. This is useful when running the provider in environments where ports may be occupied (e.g., when running alongside a proxy server or multiple stdio servers).
 
 ### Token Validation
 
@@ -207,6 +209,104 @@ const isValid = await provider.validateToken(token, serviceUrl);
 // Returns true if token is valid (200-299 status), false otherwise
 ```
 
+### Token Refresh Methods
+
+Both providers implement two refresh methods from `ITokenProvider` interface:
+
+#### refreshTokenFromSession
+
+Refreshes token using existing session data (with refreshToken):
+
+```typescript
+import { XsuaaTokenProvider } from '@mcp-abap-adt/auth-providers';
+import { ValidationError, RefreshError } from '@mcp-abap-adt/auth-providers';
+
+const provider = new XsuaaTokenProvider();
+
+const authConfig: IAuthorizationConfig = {
+  uaaUrl: 'https://...authentication...hana.ondemand.com',
+  uaaClientId: '...',
+  uaaClientSecret: '...',
+  refreshToken: '...', // From existing session
+};
+
+try {
+  const result = await provider.refreshTokenFromSession(authConfig);
+  // XSUAA uses client_credentials - no refresh token in response
+  // BTP uses browser auth - returns new refresh token
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // authConfig missing required fields
+    console.error('Missing fields:', error.missingFields); // ['uaaUrl', 'uaaClientId', ...]
+  } else if (error instanceof RefreshError) {
+    // Token refresh failed
+    console.error('Refresh failed:', error.message);
+    console.error('Original error:', error.cause);
+  }
+}
+```
+
+#### refreshTokenFromServiceKey
+
+Refreshes token using service key credentials (without refreshToken):
+
+```typescript
+try {
+  const result = await provider.refreshTokenFromServiceKey(authConfig);
+  // Both XSUAA and BTP use browser authentication for service key refresh
+  // Returns new access token and refresh token
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Missing fields:', error.missingFields);
+  } else if (error instanceof RefreshError) {
+    console.error('Browser auth failed:', error.cause);
+  }
+}
+```
+
+### Error Handling
+
+The package provides typed error classes for better error handling:
+
+```typescript
+import {
+  TokenProviderError,
+  ValidationError,
+  RefreshError,
+  SessionDataError,
+  ServiceKeyError,
+  BrowserAuthError,
+} from '@mcp-abap-adt/auth-providers';
+
+try {
+  const result = await provider.refreshTokenFromSession(authConfig);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // authConfig validation failed
+    console.error('Missing required fields:', error.missingFields);
+    console.error('Error code:', error.code); // 'VALIDATION_ERROR'
+  } else if (error instanceof RefreshError) {
+    // Token refresh operation failed
+    console.error('Refresh failed:', error.message);
+    console.error('Original error:', error.cause);
+    console.error('Error code:', error.code); // 'REFRESH_ERROR'
+  } else if (error instanceof BrowserAuthError) {
+    // Browser authentication failed
+    console.error('Browser auth failed:', error.cause);
+  }
+}
+```
+
+**Error Types**:
+- `TokenProviderError` - Base class with `code: string` property
+- `ValidationError` - authConfig validation failed, includes `missingFields: string[]`
+- `RefreshError` - Token refresh failed, includes `cause?: Error`
+- `SessionDataError` - Session data invalid, includes `missingFields: string[]`
+- `ServiceKeyError` - Service key data invalid, includes `missingFields: string[]`
+- `BrowserAuthError` - Browser auth failed, includes `cause?: Error`
+
+All error codes are defined in `@mcp-abap-adt/interfaces` package as `TOKEN_PROVIDER_ERROR_CODES`.
+
 ## Testing
 
 The package includes both unit tests (with mocks) and integration tests (with real files and services).
@@ -272,10 +372,7 @@ Example output:
 
 ## Dependencies
 
-- `@mcp-abap-adt/auth-broker` (^0.1.6) - Interface definitions
-- `@mcp-abap-adt/auth-stores` (^0.1.2) - Store implementations
-- `@mcp-abap-adt/connection` (^0.1.13) - Connection utilities
-- `@mcp-abap-adt/logger` (^0.1.0) - Logging utilities
+- `@mcp-abap-adt/interfaces` (^0.2.2) - Interface definitions and error code constants
 - `axios` - HTTP client
 - `express` - OAuth2 callback server
 - `open` - Browser opening utility

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,CAwXzD"}

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,6 +150,17 @@ 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;
         const resolve = (value) => {
@@ -137,7 +175,10 @@ async function startBrowserAuth(authConfig, browser = 'system', logger, port = 3
         };
         const app = (0, express_1.default)();
         const server = http.createServer(app);
-        const PORT = port;
+        // Disable keep-alive to ensure connections close immediately
+        server.keepAliveTimeout = 0;
+        server.headersTimeout = 0;
+        const PORT = actualPort;
         let serverInstance = null;
         const authorizationUrl = getJwtAuthorizationUrl(authConfig, PORT);
         // OAuth2 callback handler
@@ -284,36 +325,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 +404,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 +478,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 +499,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/dist/errors/TokenProviderErrors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Token Provider Error Types
+ *
+ * Defines specific error types that token providers can throw
+ * to enable better error handling and debugging.
+ */
+/**
+ * Base class for all token provider errors
+ */
+export declare class TokenProviderError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when authentication configuration is invalid or incomplete
+ */
+export declare class ValidationError extends TokenProviderError {
+    readonly missingFields?: string[] | undefined;
+    constructor(message: string, missingFields?: string[] | undefined);
+}
+/**
+ * Thrown when token refresh operation fails
+ */
+export declare class RefreshError extends TokenProviderError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Thrown when session data is invalid or incomplete
+ */
+export declare class SessionDataError extends TokenProviderError {
+    readonly missingFields?: string[] | undefined;
+    constructor(message: string, missingFields?: string[] | undefined);
+}
+/**
+ * Thrown when service key data is invalid or incomplete
+ */
+export declare class ServiceKeyError extends TokenProviderError {
+    readonly missingFields?: string[] | undefined;
+    constructor(message: string, missingFields?: string[] | undefined);
+}
+/**
+ * Thrown when browser authentication fails or is cancelled
+ */
+export declare class BrowserAuthError extends TokenProviderError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+//# sourceMappingURL=TokenProviderErrors.d.ts.map

package/dist/errors/TokenProviderErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenProviderErrors.d.ts","sourceRoot":"","sources":["../../src/errors/TokenProviderErrors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aACE,IAAI,EAAE,MAAM;gBAA7C,OAAO,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAK1D;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,kBAAkB;aACR,aAAa,CAAC,EAAE,MAAM,EAAE;gBAAzD,OAAO,EAAE,MAAM,EAAkB,aAAa,CAAC,EAAE,MAAM,EAAE,YAAA;CAKtE;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,kBAAkB;aACL,KAAK,CAAC,EAAE,KAAK;gBAA9C,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,KAAK,YAAA;CAK3D;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB;aACT,aAAa,CAAC,EAAE,MAAM,EAAE;gBAAzD,OAAO,EAAE,MAAM,EAAkB,aAAa,CAAC,EAAE,MAAM,EAAE,YAAA;CAKtE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,kBAAkB;aACR,aAAa,CAAC,EAAE,MAAM,EAAE;gBAAzD,OAAO,EAAE,MAAM,EAAkB,aAAa,CAAC,EAAE,MAAM,EAAE,YAAA;CAKtE;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB;aACT,KAAK,CAAC,EAAE,KAAK;gBAA9C,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,KAAK,YAAA;CAK3D"}

package/dist/errors/TokenProviderErrors.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Token Provider Error Types
+ *
+ * Defines specific error types that token providers can throw
+ * to enable better error handling and debugging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserAuthError = exports.ServiceKeyError = exports.SessionDataError = exports.RefreshError = exports.ValidationError = exports.TokenProviderError = void 0;
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
+/**
+ * Base class for all token provider errors
+ */
+class TokenProviderError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'TokenProviderError';
+        Object.setPrototypeOf(this, TokenProviderError.prototype);
+    }
+}
+exports.TokenProviderError = TokenProviderError;
+/**
+ * Thrown when authentication configuration is invalid or incomplete
+ */
+class ValidationError extends TokenProviderError {
+    missingFields;
+    constructor(message, missingFields) {
+        super(message, interfaces_1.TOKEN_PROVIDER_ERROR_CODES.VALIDATION_ERROR);
+        this.missingFields = missingFields;
+        this.name = 'ValidationError';
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Thrown when token refresh operation fails
+ */
+class RefreshError extends TokenProviderError {
+    cause;
+    constructor(message, cause) {
+        super(message, interfaces_1.TOKEN_PROVIDER_ERROR_CODES.REFRESH_ERROR);
+        this.cause = cause;
+        this.name = 'RefreshError';
+        Object.setPrototypeOf(this, RefreshError.prototype);
+    }
+}
+exports.RefreshError = RefreshError;
+/**
+ * Thrown when session data is invalid or incomplete
+ */
+class SessionDataError extends TokenProviderError {
+    missingFields;
+    constructor(message, missingFields) {
+        super(message, interfaces_1.TOKEN_PROVIDER_ERROR_CODES.SESSION_DATA_ERROR);
+        this.missingFields = missingFields;
+        this.name = 'SessionDataError';
+        Object.setPrototypeOf(this, SessionDataError.prototype);
+    }
+}
+exports.SessionDataError = SessionDataError;
+/**
+ * Thrown when service key data is invalid or incomplete
+ */
+class ServiceKeyError extends TokenProviderError {
+    missingFields;
+    constructor(message, missingFields) {
+        super(message, interfaces_1.TOKEN_PROVIDER_ERROR_CODES.SERVICE_KEY_ERROR);
+        this.missingFields = missingFields;
+        this.name = 'ServiceKeyError';
+        Object.setPrototypeOf(this, ServiceKeyError.prototype);
+    }
+}
+exports.ServiceKeyError = ServiceKeyError;
+/**
+ * Thrown when browser authentication fails or is cancelled
+ */
+class BrowserAuthError extends TokenProviderError {
+    cause;
+    constructor(message, cause) {
+        super(message, interfaces_1.TOKEN_PROVIDER_ERROR_CODES.BROWSER_AUTH_ERROR);
+        this.cause = cause;
+        this.name = 'BrowserAuthError';
+        Object.setPrototypeOf(this, BrowserAuthError.prototype);
+    }
+}
+exports.BrowserAuthError = BrowserAuthError;

package/dist/index.d.ts

@@ -6,4 +6,5 @@
  */
 export { XsuaaTokenProvider } from './providers/XsuaaTokenProvider';
 export { BtpTokenProvider } from './providers/BtpTokenProvider';
+export { TokenProviderError, ValidationError, RefreshError, SessionDataError, ServiceKeyError, BrowserAuthError, } from './errors/TokenProviderErrors';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -6,9 +6,17 @@
  * Provides XSUAA and BTP token providers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BtpTokenProvider = exports.XsuaaTokenProvider = void 0;
+exports.BrowserAuthError = exports.ServiceKeyError = exports.SessionDataError = exports.RefreshError = exports.ValidationError = exports.TokenProviderError = exports.BtpTokenProvider = exports.XsuaaTokenProvider = void 0;
 // Token providers
 var XsuaaTokenProvider_1 = require("./providers/XsuaaTokenProvider");
 Object.defineProperty(exports, "XsuaaTokenProvider", { enumerable: true, get: function () { return XsuaaTokenProvider_1.XsuaaTokenProvider; } });
 var BtpTokenProvider_1 = require("./providers/BtpTokenProvider");
 Object.defineProperty(exports, "BtpTokenProvider", { enumerable: true, get: function () { return BtpTokenProvider_1.BtpTokenProvider; } });
+// Errors
+var TokenProviderErrors_1 = require("./errors/TokenProviderErrors");
+Object.defineProperty(exports, "TokenProviderError", { enumerable: true, get: function () { return TokenProviderErrors_1.TokenProviderError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return TokenProviderErrors_1.ValidationError; } });
+Object.defineProperty(exports, "RefreshError", { enumerable: true, get: function () { return TokenProviderErrors_1.RefreshError; } });
+Object.defineProperty(exports, "SessionDataError", { enumerable: true, get: function () { return TokenProviderErrors_1.SessionDataError; } });
+Object.defineProperty(exports, "ServiceKeyError", { enumerable: true, get: function () { return TokenProviderErrors_1.ServiceKeyError; } });
+Object.defineProperty(exports, "BrowserAuthError", { enumerable: true, get: function () { return TokenProviderErrors_1.BrowserAuthError; } });

package/dist/providers/BtpTokenProvider.d.ts

@@ -23,6 +23,8 @@ export declare class BtpTokenProvider implements ITokenProvider {
      */
     private refreshJwtToken;
     getConnectionConfig(authConfig: IAuthorizationConfig, options?: ITokenProviderOptions): Promise<ITokenProviderResult>;
+    refreshTokenFromSession(authConfig: IAuthorizationConfig, options?: ITokenProviderOptions): Promise<ITokenProviderResult>;
+    refreshTokenFromServiceKey(authConfig: IAuthorizationConfig, options?: ITokenProviderOptions): Promise<ITokenProviderResult>;
     validateToken(token: string, serviceUrl?: string): Promise<boolean>;
 }
 //# sourceMappingURL=BtpTokenProvider.d.ts.map

package/dist/providers/BtpTokenProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BtpTokenProvider.d.ts","sourceRoot":"","sources":["../../src/providers/BtpTokenProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAW,MAAM,0BAA0B,CAAC;AAO3I;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,eAAe,CAAC,EAAE,MAAM;IAKpC;;;OAGG;YACW,gBAAgB;IAQ9B;;OAEG;YACW,eAAe;IASvB,mBAAmB,CACvB,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAmC1B,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA0C1E"}
+{"version":3,"file":"BtpTokenProvider.d.ts","sourceRoot":"","sources":["../../src/providers/BtpTokenProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAW,MAAM,0BAA0B,CAAC;AAQ3I;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,eAAe,CAAC,EAAE,MAAM;IAKpC;;;OAGG;YACW,gBAAgB;IAQ9B;;OAEG;YACW,eAAe;IASvB,mBAAmB,CACvB,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAmC1B,uBAAuB,CAC3B,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAuC1B,0BAA0B,CAC9B,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAuC1B,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA0C1E"}

package/dist/providers/BtpTokenProvider.js

@@ -10,6 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BtpTokenProvider = void 0;
+const TokenProviderErrors_1 = require("../errors/TokenProviderErrors");
 const axios_1 = __importDefault(require("axios"));
 // Import internal functions (not exported)
 const browserAuth_1 = require("../auth/browserAuth");
@@ -65,6 +66,68 @@ class BtpTokenProvider {
             refreshToken: result.refreshToken,
         };
     }
+    async refreshTokenFromSession(authConfig, options) {
+        const logger = options?.logger;
+        const browser = options?.browser || 'system';
+        // Validate authConfig
+        const missingFields = [];
+        if (!authConfig.uaaUrl)
+            missingFields.push('uaaUrl');
+        if (!authConfig.uaaClientId)
+            missingFields.push('uaaClientId');
+        if (!authConfig.uaaClientSecret)
+            missingFields.push('uaaClientSecret');
+        if (missingFields.length > 0) {
+            throw new TokenProviderErrors_1.ValidationError(`BTP refreshTokenFromSession: authConfig missing required fields: ${missingFields.join(', ')}`, missingFields);
+        }
+        if (logger) {
+            logger.debug('BTP: Refreshing token from session using browser authentication (UAA_URL)...');
+        }
+        // BTP refresh from session uses browser authentication through UAA_URL
+        try {
+            const result = await this.startBrowserAuth(authConfig, browser, logger);
+            return {
+                connectionConfig: {
+                    authorizationToken: result.accessToken,
+                },
+                refreshToken: result.refreshToken,
+            };
+        }
+        catch (error) {
+            throw new TokenProviderErrors_1.RefreshError(`BTP refreshTokenFromSession failed: ${error.message}`, error);
+        }
+    }
+    async refreshTokenFromServiceKey(authConfig, options) {
+        const logger = options?.logger;
+        const browser = options?.browser || 'system';
+        // Validate authConfig
+        const missingFields = [];
+        if (!authConfig.uaaUrl)
+            missingFields.push('uaaUrl');
+        if (!authConfig.uaaClientId)
+            missingFields.push('uaaClientId');
+        if (!authConfig.uaaClientSecret)
+            missingFields.push('uaaClientSecret');
+        if (missingFields.length > 0) {
+            throw new TokenProviderErrors_1.ValidationError(`BTP refreshTokenFromServiceKey: authConfig missing required fields: ${missingFields.join(', ')}`, missingFields);
+        }
+        if (logger) {
+            logger.debug('BTP: Refreshing token from service key using browser authentication...');
+        }
+        // BTP refresh from service key uses browser authentication
+        try {
+            const result = await this.startBrowserAuth(authConfig, browser, logger);
+            return {
+                connectionConfig: {
+                    authorizationToken: result.accessToken,
+                },
+                refreshToken: result.refreshToken,
+            };
+        }
+        catch (error) {
+            throw new TokenProviderErrors_1.RefreshError(`BTP refreshTokenFromServiceKey failed: ${error.message}`, error);
+        }
+    }
     async validateToken(token, serviceUrl) {
         if (!token || !serviceUrl) {
             return false;

package/dist/providers/XsuaaTokenProvider.d.ts

@@ -16,6 +16,8 @@ export declare class XsuaaTokenProvider implements ITokenProvider {
      */
     private getTokenWithClientCredentials;
     getConnectionConfig(authConfig: IAuthorizationConfig, options?: ITokenProviderOptions): Promise<ITokenProviderResult>;
+    refreshTokenFromSession(authConfig: IAuthorizationConfig, options?: ITokenProviderOptions): Promise<ITokenProviderResult>;
+    refreshTokenFromServiceKey(authConfig: IAuthorizationConfig, options?: ITokenProviderOptions): Promise<ITokenProviderResult>;
     validateToken(token: string, serviceUrl?: string): Promise<boolean>;
 }
 //# sourceMappingURL=XsuaaTokenProvider.d.ts.map

package/dist/providers/XsuaaTokenProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XsuaaTokenProvider.d.ts","sourceRoot":"","sources":["../../src/providers/XsuaaTokenProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAMlI;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD;;OAEG;YACW,6BAA6B;IAQrC,mBAAmB,CACvB,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAyB1B,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAgD1E"}
+{"version":3,"file":"XsuaaTokenProvider.d.ts","sourceRoot":"","sources":["../../src/providers/XsuaaTokenProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAOlI;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD;;OAEG;YACW,6BAA6B;IAQrC,mBAAmB,CACvB,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAyB1B,uBAAuB,CAC3B,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IA2C1B,0BAA0B,CAC9B,UAAU,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IAwC1B,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAgD1E"}

package/dist/providers/XsuaaTokenProvider.js

@@ -5,11 +5,45 @@
  * Uses client_credentials grant type to obtain tokens (no browser required).
  * For XSUAA service keys with reduced scope access.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.XsuaaTokenProvider = void 0;
+const TokenProviderErrors_1 = require("../errors/TokenProviderErrors");
 const axios_1 = __importDefault(require("axios"));
 // Import internal function (not exported)
 const clientCredentialsAuth_1 = require("../auth/clientCredentialsAuth");
@@ -42,6 +76,68 @@ class XsuaaTokenProvider {
             // XSUAA client_credentials doesn't provide refresh token
         };
     }
+    async refreshTokenFromSession(authConfig, options) {
+        const logger = options?.logger;
+        // Validate authConfig
+        const missingFields = [];
+        if (!authConfig.uaaUrl)
+            missingFields.push('uaaUrl');
+        if (!authConfig.uaaClientId)
+            missingFields.push('uaaClientId');
+        if (!authConfig.uaaClientSecret)
+            missingFields.push('uaaClientSecret');
+        if (missingFields.length > 0) {
+            throw new TokenProviderErrors_1.ValidationError(`XSUAA refreshTokenFromSession: authConfig missing required fields: ${missingFields.join(', ')}`, missingFields);
+        }
+        if (logger) {
+            logger.debug('XSUAA: Refreshing token from session using client_credentials...');
+        }
+        // XSUAA refresh from session uses client_credentials (clientId/clientSecret)
+        try {
+            const result = await this.getTokenWithClientCredentials(authConfig.uaaUrl, authConfig.uaaClientId, authConfig.uaaClientSecret);
+            return {
+                connectionConfig: {
+                    authorizationToken: result.accessToken,
+                },
+                // XSUAA client_credentials doesn't provide refresh token
+            };
+        }
+        catch (error) {
+            throw new TokenProviderErrors_1.RefreshError(`XSUAA refreshTokenFromSession failed: ${error.message}`, error);
+        }
+    }
+    async refreshTokenFromServiceKey(authConfig, options) {
+        const logger = options?.logger;
+        const browser = options?.browser || 'system';
+        // Validate authConfig
+        const missingFields = [];
+        if (!authConfig.uaaUrl)
+            missingFields.push('uaaUrl');
+        if (!authConfig.uaaClientId)
+            missingFields.push('uaaClientId');
+        if (!authConfig.uaaClientSecret)
+            missingFields.push('uaaClientSecret');
+        if (missingFields.length > 0) {
+            throw new TokenProviderErrors_1.ValidationError(`XSUAA refreshTokenFromServiceKey: authConfig missing required fields: ${missingFields.join(', ')}`, missingFields);
+        }
+        if (logger) {
+            logger.debug('XSUAA: Refreshing token from service key using browser authentication...');
+        }
+        // XSUAA refresh from service key uses browser authentication
+        try {
+            const { startBrowserAuth } = await Promise.resolve().then(() => __importStar(require('../auth/browserAuth')));
+            const result = await startBrowserAuth(authConfig, browser, logger);
+            return {
+                connectionConfig: {
+                    authorizationToken: result.accessToken,
+                },
+                refreshToken: result.refreshToken,
+            };
+        }
+        catch (error) {
+            throw new TokenProviderErrors_1.RefreshError(`XSUAA refreshTokenFromServiceKey failed: ${error.message}`, error);
+        }
+    }
     async validateToken(token, serviceUrl) {
         // XSUAA tokens are validated by the service itself when making requests
         // If serviceUrl is provided, we can test the connection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/auth-providers",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Token providers for MCP ABAP ADT auth-broker - XSUAA and BTP token providers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -48,7 +48,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@mcp-abap-adt/interfaces": "^0.1.16",
+    "@mcp-abap-adt/interfaces": "^0.2.2",
     "axios": "^1.11.0",
     "express": "^5.1.0",
     "open": "^11.0.0"