@mcp-abap-adt/auth-broker 0.2.8 → 0.2.10

package/dist/AuthBroker.js

@@ -14,6 +14,23 @@ const noOpLogger = {
     warn: () => { },
     debug: () => { },
 };
+/**
+ * Helper function to check if error has a code property
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Helper function needs to accept any error type
+function hasErrorCode(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'code' in error &&
+        typeof error.code === 'string');
+}
+/**
+ * Helper function to get error message safely
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Helper function needs to accept any error type
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /**
  * AuthBroker manages JWT authentication tokens for destinations
  */
@@ -94,82 +111,55 @@ class AuthBroker {
         this.logger?.debug(`AuthBroker initialized: sessionStore(ok), serviceKeyStore(${hasServiceKeyStore ? 'ok' : 'none'}), tokenProvider(ok)`);
     }
     /**
-     * Get authentication token for destination.
-     * Uses tokenProvider for all authentication operations (browser-based authorization).
-     *
-     * **Flow:**
-     * **Step 0: Initialize Session with Token (if needed)**
-     * - Check if session has `authorizationToken` AND UAA credentials
-     * - If both are empty AND serviceKeyStore is available:
-     *   - Get UAA credentials from service key
-     *   - Use tokenProvider for browser-based authentication
-     *   - Save token and refresh token to session
-     *
-     * **Step 1: Token Validation**
-     * - If token exists in session, validate it (if provider supports validation)
-     * - If valid → return token
-     * - If invalid or no token → continue to refresh
-     *
-     * **Step 2: Refresh Token Flow**
-     * - Check if refresh token exists in session
-     * - If refresh token exists:
-     *   - Use tokenProvider to refresh token (browser-based or refresh grant)
-     *   - Save new token to session
-     *   - Return new token
-     * - Otherwise → proceed to Step 3
-     *
-     * **Step 3: New Token Flow**
-     * - Get UAA credentials from session or service key
-     * - Use tokenProvider for browser-based authentication
-     * - Save new token to session
-     * - Return new token
-     *
-     * **Important Notes:**
-     * - All authentication is handled by tokenProvider (e.g., XSUAA provider)
-     * - Provider uses browser-based authorization to ensure proper role assignment
-     * - Direct UAA HTTP requests are not used to avoid role assignment issues
-     *
-     * @param destination Destination name (e.g., "TRIAL")
-     * @returns Promise that resolves to JWT token string
-     * @throws Error if session initialization fails or authentication failed
+     * Load session data (connection and authorization configs)
      */
-    async getToken(destination) {
-        this.logger?.debug(`Getting token for destination: ${destination}`);
-        // Step 0: Initialize Session with Token (if needed)
+    async loadSessionData(destination) {
         let connConfig = null;
         let authConfig = null;
         try {
             connConfig = await this.sessionStore.getConnectionConfig(destination);
         }
         catch (error) {
-            // Handle typed store errors from session store
-            if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
-                this.logger?.debug(`Session file not found for ${destination}: ${error.filePath || 'unknown path'}`);
-            }
-            else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
-                this.logger?.warn(`Failed to parse session file for ${destination}: ${error.filePath || 'unknown path'} - ${error.message}`);
+            if (hasErrorCode(error)) {
+                if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
+                    this.logger?.debug(`Session file not found for ${destination}: ${error.filePath || 'unknown path'}`);
+                }
+                else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
+                    this.logger?.warn(`Failed to parse session file for ${destination}: ${error.filePath || 'unknown path'} - ${getErrorMessage(error)}`);
+                }
+                else {
+                    this.logger?.warn(`Failed to get connection config from session store for ${destination}: ${getErrorMessage(error)}`);
+                }
             }
             else {
-                this.logger?.warn(`Failed to get connection config from session store for ${destination}: ${error.message}`);
+                this.logger?.warn(`Failed to get connection config from session store for ${destination}: ${getErrorMessage(error)}`);
             }
         }
         try {
             authConfig = await this.sessionStore.getAuthorizationConfig(destination);
         }
         catch (error) {
-            // Handle typed store errors from session store
-            if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
-                this.logger?.debug(`Session file not found for ${destination}: ${error.filePath || 'unknown path'}`);
-            }
-            else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
-                this.logger?.warn(`Failed to parse session file for ${destination}: ${error.filePath || 'unknown path'} - ${error.message}`);
+            if (hasErrorCode(error)) {
+                if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
+                    this.logger?.debug(`Session file not found for ${destination}: ${error.filePath || 'unknown path'}`);
+                }
+                else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
+                    this.logger?.warn(`Failed to parse session file for ${destination}: ${error.filePath || 'unknown path'} - ${getErrorMessage(error)}`);
+                }
+                else {
+                    this.logger?.warn(`Failed to get authorization config from session store for ${destination}: ${getErrorMessage(error)}`);
+                }
             }
             else {
-                this.logger?.warn(`Failed to get authorization config from session store for ${destination}: ${error.message}`);
+                this.logger?.warn(`Failed to get authorization config from session store for ${destination}: ${getErrorMessage(error)}`);
             }
         }
-        // Check if session has serviceUrl (required)
-        // If not in session, try to get it from serviceKeyStore
+        return { connConfig, authConfig };
+    }
+    /**
+     * Get serviceUrl from session or service key store
+     */
+    async getServiceUrl(destination, connConfig) {
         let serviceUrl = connConfig?.serviceUrl;
         if (!serviceUrl && this.serviceKeyStore) {
             try {
@@ -180,15 +170,19 @@ class AuthBroker {
                 }
             }
             catch (error) {
-                // Handle typed store errors
-                if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
-                    this.logger?.debug(`Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
-                }
-                else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
-                    this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${error.message}`);
+                if (hasErrorCode(error)) {
+                    if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
+                        this.logger?.debug(`Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
+                    }
+                    else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
+                        this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${getErrorMessage(error)}`);
+                    }
+                    else {
+                        this.logger?.warn(`Failed to get serviceUrl from service key store for ${destination}: ${getErrorMessage(error)}`);
+                    }
                 }
                 else {
-                    this.logger?.warn(`Failed to get serviceUrl from service key store for ${destination}: ${error.message}`);
+                    this.logger?.warn(`Failed to get serviceUrl from service key store for ${destination}: ${getErrorMessage(error)}`);
                 }
             }
         }
@@ -197,307 +191,388 @@ class AuthBroker {
             throw new Error(`Session for destination "${destination}" is missing required field 'serviceUrl'. ` +
                 `SessionStore must contain initial session with serviceUrl${this.serviceKeyStore ? ' or serviceKeyStore must contain serviceUrl' : ''}.`);
         }
-        // Check if we have token or UAA credentials
-        const hasToken = !!connConfig?.authorizationToken;
-        const hasUaaCredentials = !!(authConfig?.uaaUrl && authConfig?.uaaClientId && authConfig?.uaaClientSecret);
-        this.logger?.debug(`Step 0: Session check for ${destination}: hasToken(${hasToken}), hasUaaCredentials(${hasUaaCredentials}), serviceUrl(${serviceUrl ? 'yes' : 'no'})`);
-        // If token is empty AND UAA fields are empty, try to initialize from service key
-        if (!hasToken && !hasUaaCredentials) {
-            this.logger?.debug(`Step 0: Token and UAA credentials are empty for ${destination}, attempting initialization from service key`);
-            if (!this.serviceKeyStore) {
-                this.logger?.error(`Step 0: Cannot initialize session for ${destination}: authorizationToken is empty, UAA credentials are empty, and serviceKeyStore is not available`);
-                throw new Error(`Cannot initialize session for destination "${destination}": authorizationToken is empty, UAA credentials are empty, and serviceKeyStore is not available. ` +
-                    `Provide serviceKeyStore to initialize from service key.`);
-            }
-            try {
-                // Get UAA credentials from service key
-                const serviceKeyAuthConfig = await this.serviceKeyStore.getAuthorizationConfig(destination);
-                if (!serviceKeyAuthConfig || !serviceKeyAuthConfig.uaaUrl || !serviceKeyAuthConfig.uaaClientId || !serviceKeyAuthConfig.uaaClientSecret) {
-                    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;
-                try {
-                    tokenResult = await this.tokenProvider.getConnectionConfig(serviceKeyAuthConfig, {
-                        browser: this.browser,
-                        logger: this.logger,
-                    });
-                }
-                catch (error) {
-                    // Handle provider errors (network, auth, validation)
-                    if (error.code === 'VALIDATION_ERROR') {
-                        this.logger?.error(`Step 0: Provider validation error for ${destination}: missing ${error.missingFields?.join(', ') || 'required fields'}`);
-                        throw new Error(`Cannot initialize session for destination "${destination}": provider validation failed - missing ${error.missingFields?.join(', ') || 'required fields'}`);
-                    }
-                    else if (error.code === 'BROWSER_AUTH_ERROR') {
-                        this.logger?.error(`Step 0: Browser authentication failed for ${destination}: ${error.message}`);
-                        throw new Error(`Cannot initialize session for destination "${destination}": browser authentication failed - ${error.message}`);
-                    }
-                    else if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') {
-                        this.logger?.error(`Step 0: Network error for ${destination}: ${error.code}`);
-                        throw new Error(`Cannot initialize session for destination "${destination}": network error - cannot reach authentication server (${error.code})`);
-                    }
-                    this.logger?.error(`Step 0: Provider error for ${destination}: ${error.message}`);
-                    throw new Error(`Cannot initialize session for destination "${destination}": provider error - ${error.message}`);
-                }
-                const tokenLength = tokenResult.connectionConfig.authorizationToken?.length || 0;
-                this.logger?.info(`Step 0: Token initialized for ${destination}: token(${tokenLength} chars), hasRefreshToken(${!!tokenResult.refreshToken})`);
-                // Get serviceUrl from service key store if not in connectionConfig
-                const serviceKeyConnConfig = await this.serviceKeyStore.getConnectionConfig(destination);
-                const connectionConfigWithServiceUrl = {
-                    ...tokenResult.connectionConfig,
-                    serviceUrl: tokenResult.connectionConfig.serviceUrl || serviceKeyConnConfig?.serviceUrl || serviceUrl,
-                };
-                // Save token and UAA credentials to session
-                try {
-                    await this.sessionStore.setConnectionConfig(destination, connectionConfigWithServiceUrl);
-                }
-                catch (error) {
-                    this.logger?.error(`Step 0: Failed to save connection config to session for ${destination}: ${error.message}`);
-                    throw new Error(`Failed to save connection config for destination "${destination}": ${error.message}`);
-                }
-                try {
-                    await this.sessionStore.setAuthorizationConfig(destination, {
-                        ...serviceKeyAuthConfig,
-                        refreshToken: tokenResult.refreshToken || serviceKeyAuthConfig.refreshToken,
-                    });
-                }
-                catch (error) {
-                    this.logger?.error(`Step 0: Failed to save authorization config to session for ${destination}: ${error.message}`);
-                    throw new Error(`Failed to save authorization config for destination "${destination}": ${error.message}`);
-                }
-                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'}`);
-                    throw new Error(`Cannot initialize session for destination "${destination}": service key file not found`);
-                }
-                else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
-                    this.logger?.error(`Step 0: Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${error.message}`);
-                    throw new Error(`Cannot initialize session for destination "${destination}": service key parsing failed - ${error.message}`);
-                }
-                else if (error.code === interfaces_1.STORE_ERROR_CODES.INVALID_CONFIG) {
-                    this.logger?.error(`Step 0: Invalid service key config for ${destination}: missing fields ${error.missingFields?.join(', ') || 'unknown'}`);
-                    throw new Error(`Cannot initialize session for destination "${destination}": invalid service key - missing ${error.missingFields?.join(', ') || 'required fields'}`);
-                }
-                this.logger?.error(`Step 0: Failed to initialize session for ${destination}: ${error.message}`);
-                throw new Error(`Cannot initialize session for destination "${destination}": ${error.message}`);
-            }
+        return serviceUrl;
+    }
+    /**
+     * Get UAA credentials from session or service key
+     */
+    async getUaaCredentials(destination, authConfig) {
+        if (authConfig?.uaaUrl &&
+            authConfig?.uaaClientId &&
+            authConfig?.uaaClientSecret) {
+            return authConfig;
         }
-        // If we have a token, validate it first
-        if (hasToken && connConfig?.authorizationToken) {
-            this.logger?.debug(`Step 0: Token found for ${destination}, validating`);
-            // Validate token if provider supports validation and we have service URL
-            if (this.tokenProvider?.validateToken && serviceUrl) {
-                try {
-                    const isValid = await this.tokenProvider.validateToken(connConfig.authorizationToken, serviceUrl);
-                    if (isValid) {
-                        this.logger?.info(`Step 0: Token valid for ${destination}: token(${connConfig.authorizationToken.length} chars)`);
-                        return connConfig.authorizationToken;
-                    }
-                    this.logger?.debug(`Step 0: Token invalid for ${destination}, continuing to refresh`);
-                }
-                catch (error) {
-                    // Validation failed due to network/server error - log and continue to refresh
-                    this.logger?.warn(`Step 0: Token validation failed for ${destination} (network error): ${error.message}. Continuing to refresh.`);
-                    // Don't throw - continue to refresh flow
-                }
-            }
-            else {
-                // No service URL or provider doesn't support validation - just return token
-                this.logger?.info(`Step 0: Token found for ${destination} (no validation): token(${connConfig.authorizationToken.length} chars)`);
-                return connConfig.authorizationToken;
-            }
+        if (!this.serviceKeyStore) {
+            throw new Error(`UAA credentials not found for ${destination}. Session has no UAA credentials and serviceKeyStore is not available.`);
         }
-        // Step 2: Refresh Token Flow
-        this.logger?.debug(`Step 2: Attempting token refresh for ${destination}`);
-        // Get UAA credentials from session or service key
         let serviceKeyAuthConfig = null;
-        if (!authConfig && this.serviceKeyStore) {
-            try {
-                serviceKeyAuthConfig = await this.serviceKeyStore.getAuthorizationConfig(destination);
-            }
-            catch (error) {
-                // Handle typed store errors
+        try {
+            serviceKeyAuthConfig =
+                await this.serviceKeyStore.getAuthorizationConfig(destination);
+        }
+        catch (error) {
+            if (hasErrorCode(error)) {
                 if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
                     this.logger?.debug(`Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
                 }
                 else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
-                    this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${error.message}`);
+                    this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${getErrorMessage(error)}`);
                 }
                 else {
-                    this.logger?.warn(`Failed to get UAA credentials from service key store for ${destination}: ${error.message}`);
+                    this.logger?.warn(`Failed to get UAA credentials from service key store for ${destination}: ${getErrorMessage(error)}`);
                 }
             }
+            else {
+                this.logger?.warn(`Failed to get UAA credentials from service key store for ${destination}: ${getErrorMessage(error)}`);
+            }
         }
         const uaaCredentials = authConfig || serviceKeyAuthConfig;
-        if (!uaaCredentials || !uaaCredentials.uaaUrl || !uaaCredentials.uaaClientId || !uaaCredentials.uaaClientSecret) {
-            const errorMessage = `Step 2: UAA credentials not found for ${destination}. ` +
-                `Session has no UAA credentials${this.serviceKeyStore ? ' and serviceKeyStore has no UAA credentials' : ' and serviceKeyStore is not available'}.`;
-            this.logger?.error(errorMessage);
-            throw new Error(errorMessage);
+        if (!uaaCredentials ||
+            !uaaCredentials.uaaUrl ||
+            !uaaCredentials.uaaClientId ||
+            !uaaCredentials.uaaClientSecret) {
+            throw new Error(`UAA credentials not found for ${destination}. Session has no UAA credentials${this.serviceKeyStore ? ' and serviceKeyStore has no UAA credentials' : ' and serviceKeyStore is not available'}.`);
         }
-        // Try refresh from session first (if refresh token exists)
-        const refreshToken = authConfig?.refreshToken;
-        if (refreshToken) {
-            try {
-                this.logger?.debug(`Step 2a: Trying refreshTokenFromSession for ${destination}`);
-                const authConfigWithRefresh = { ...uaaCredentials, refreshToken };
-                let tokenResult;
-                try {
-                    tokenResult = await this.tokenProvider.refreshTokenFromSession(authConfigWithRefresh, {
-                        browser: this.browser,
-                        logger: this.logger,
-                    });
-                }
-                catch (providerError) {
-                    // Handle provider network/auth errors
-                    if (providerError.code === 'ECONNREFUSED' || providerError.code === 'ETIMEDOUT' || providerError.code === 'ENOTFOUND') {
-                        this.logger?.debug(`Step 2a: Network error during refreshTokenFromSession for ${destination}: ${providerError.code}. Trying refreshTokenFromServiceKey`);
-                        throw providerError; // Re-throw to trigger fallback to Step 2b
-                    }
-                    throw providerError; // Re-throw other errors
-                }
-                const tokenLength = tokenResult.connectionConfig.authorizationToken?.length || 0;
-                this.logger?.info(`Step 2a: Token refreshed from session for ${destination}: token(${tokenLength} chars), hasRefreshToken(${!!tokenResult.refreshToken})`);
-                // Get serviceUrl from session or service key
-                let serviceKeyServiceUrl;
-                if (this.serviceKeyStore) {
-                    try {
-                        const serviceKeyConn = await this.serviceKeyStore.getConnectionConfig(destination);
-                        serviceKeyServiceUrl = serviceKeyConn?.serviceUrl;
-                    }
-                    catch (error) {
-                        this.logger?.debug(`Could not get serviceUrl from service key store: ${error.message}`);
-                    }
-                }
-                const finalServiceUrl = tokenResult.connectionConfig.serviceUrl || serviceUrl || serviceKeyServiceUrl;
-                const connectionConfigWithServiceUrl = {
-                    ...tokenResult.connectionConfig,
-                    serviceUrl: finalServiceUrl,
-                };
-                // Update session with new token
-                try {
-                    await this.sessionStore.setConnectionConfig(destination, connectionConfigWithServiceUrl);
-                }
-                catch (error) {
-                    this.logger?.error(`Step 2a: Failed to save connection config to session for ${destination}: ${error.message}`);
-                    throw new Error(`Failed to save connection config for destination "${destination}": ${error.message}`);
-                }
-                if (tokenResult.refreshToken) {
-                    try {
-                        await this.sessionStore.setAuthorizationConfig(destination, {
-                            ...uaaCredentials,
-                            refreshToken: tokenResult.refreshToken,
-                        });
-                    }
-                    catch (error) {
-                        this.logger?.error(`Step 2a: Failed to save authorization config to session for ${destination}: ${error.message}`);
-                        throw new Error(`Failed to save authorization config for destination "${destination}": ${error.message}`);
-                    }
-                }
-                return tokenResult.connectionConfig.authorizationToken;
+        return uaaCredentials;
+    }
+    /**
+     * Save token and config to session
+     */
+    async saveTokenToSession(destination, connectionConfig, authorizationConfig) {
+        try {
+            await this.sessionStore.setConnectionConfig(destination, connectionConfig);
+        }
+        catch (error) {
+            this.logger?.error(`Failed to save connection config to session for ${destination}: ${getErrorMessage(error)}`);
+            throw new Error(`Failed to save connection config for destination "${destination}": ${getErrorMessage(error)}`);
+        }
+        try {
+            await this.sessionStore.setAuthorizationConfig(destination, authorizationConfig);
+        }
+        catch (error) {
+            this.logger?.error(`Failed to save authorization config to session for ${destination}: ${getErrorMessage(error)}`);
+            throw new Error(`Failed to save authorization config for destination "${destination}": ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Initialize session from service key (Step 0)
+     */
+    async initializeSessionFromServiceKey(destination, serviceUrl) {
+        if (!this.serviceKeyStore) {
+            throw new Error(`Cannot initialize session for destination "${destination}": authorizationToken is empty, UAA credentials are empty, and serviceKeyStore is not available. Provide serviceKeyStore to initialize from service key.`);
+        }
+        const serviceKeyAuthConfig = await this.serviceKeyStore.getAuthorizationConfig(destination);
+        if (!serviceKeyAuthConfig ||
+            !serviceKeyAuthConfig.uaaUrl ||
+            !serviceKeyAuthConfig.uaaClientId ||
+            !serviceKeyAuthConfig.uaaClientSecret) {
+            throw new Error(`Service key for destination "${destination}" does not contain UAA credentials`);
+        }
+        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;
+        }
+        this.logger?.debug(`Step 0: Authenticating via provider (browser) for ${destination} using service key UAA credentials`);
+        let tokenResult;
+        try {
+            tokenResult = await this.tokenProvider.getConnectionConfig(serviceKeyAuthConfig, {
+                browser: this.browser,
+                logger: this.logger,
+            });
+        }
+        catch (error) {
+            if (hasErrorCode(error)) {
+                if (error.code === 'VALIDATION_ERROR') {
+                    throw new Error(`Cannot initialize session for destination "${destination}": provider validation failed - missing ${error.missingFields?.join(', ') || 'required fields'}`);
+                }
+                else if (error.code === 'BROWSER_AUTH_ERROR') {
+                    throw new Error(`Cannot initialize session for destination "${destination}": browser authentication failed - ${getErrorMessage(error)}`);
+                }
+                else if (error.code === 'ECONNREFUSED' ||
+                    error.code === 'ETIMEDOUT' ||
+                    error.code === 'ENOTFOUND') {
+                    throw new Error(`Cannot initialize session for destination "${destination}": network error - cannot reach authentication server (${error.code})`);
+                }
+            }
+            throw new Error(`Cannot initialize session for destination "${destination}": provider error - ${getErrorMessage(error)}`);
+        }
+        const token = tokenResult.connectionConfig.authorizationToken;
+        if (!token) {
+            throw new Error(`Token provider did not return authorization token for destination "${destination}"`);
+        }
+        const tokenLength = token.length;
+        this.logger?.info(`Step 0: Token initialized for ${destination}: token(${tokenLength} chars), hasRefreshToken(${!!tokenResult.refreshToken})`);
+        // Get serviceUrl from service key store if not in connectionConfig
+        const serviceKeyConnConfig = await this.serviceKeyStore.getConnectionConfig(destination);
+        const connectionConfigWithServiceUrl = {
+            ...tokenResult.connectionConfig,
+            serviceUrl: tokenResult.connectionConfig.serviceUrl ||
+                serviceKeyConnConfig?.serviceUrl ||
+                serviceUrl,
+        };
+        await this.saveTokenToSession(destination, connectionConfigWithServiceUrl, {
+            ...serviceKeyAuthConfig,
+            refreshToken: tokenResult.refreshToken || serviceKeyAuthConfig.refreshToken,
+        });
+        return token;
+    }
+    /**
+     * Validate existing token (Step 1)
+     */
+    async validateExistingToken(destination, token, serviceUrl) {
+        if (!this.tokenProvider?.validateToken) {
+            return false;
+        }
+        try {
+            const isValid = await this.tokenProvider.validateToken(token, serviceUrl);
+            if (isValid) {
+                this.logger?.info(`Step 1: Token valid for ${destination}: token(${token.length} chars)`);
+                return true;
             }
-            catch (error) {
-                this.logger?.debug(`Step 2a: refreshTokenFromSession failed for ${destination}: ${error.message}, trying refreshTokenFromServiceKey`);
-                // Continue to try service key refresh
+            this.logger?.debug(`Step 1: Token invalid for ${destination}, continuing to refresh`);
+            return false;
+        }
+        catch (error) {
+            // Validation failed due to network/server error - log and continue to refresh
+            this.logger?.warn(`Step 1: Token validation failed for ${destination} (network error): ${getErrorMessage(error)}. Continuing to refresh.`);
+            return false;
+        }
+    }
+    /**
+     * Refresh token from session (Step 2a)
+     */
+    async refreshTokenFromSession(destination, uaaCredentials, refreshToken, serviceUrl) {
+        this.logger?.debug(`Step 2a: Trying refreshTokenFromSession for ${destination}`);
+        const authConfigWithRefresh = { ...uaaCredentials, refreshToken };
+        let tokenResult;
+        try {
+            tokenResult = await this.tokenProvider.refreshTokenFromSession(authConfigWithRefresh, {
+                browser: this.browser,
+                logger: this.logger,
+            });
+        }
+        catch (error) {
+            if (hasErrorCode(error)) {
+                if (error.code === 'ECONNREFUSED' ||
+                    error.code === 'ETIMEDOUT' ||
+                    error.code === 'ENOTFOUND') {
+                    this.logger?.debug(`Step 2a: Network error during refreshTokenFromSession for ${destination}: ${error.code}. Trying refreshTokenFromServiceKey`);
+                    throw error; // Re-throw to trigger fallback to Step 2b
+                }
             }
+            throw error; // Re-throw other errors
         }
-        else {
-            this.logger?.debug(`Step 2a: No refresh token in session for ${destination}, skipping to service key refresh`);
+        const token = tokenResult.connectionConfig.authorizationToken;
+        if (!token) {
+            throw new Error(`Token provider did not return authorization token for destination "${destination}"`);
         }
-        // Try refresh from service key (browser authentication)
-        // Check if browser auth is allowed
+        const tokenLength = token.length;
+        this.logger?.info(`Step 2a: Token refreshed from session for ${destination}: token(${tokenLength} chars), hasRefreshToken(${!!tokenResult.refreshToken})`);
+        // Get serviceUrl from session or service key
+        let serviceKeyServiceUrl;
+        if (this.serviceKeyStore) {
+            try {
+                const serviceKeyConn = await this.serviceKeyStore.getConnectionConfig(destination);
+                serviceKeyServiceUrl = serviceKeyConn?.serviceUrl;
+            }
+            catch (error) {
+                this.logger?.debug(`Could not get serviceUrl from service key store: ${getErrorMessage(error)}`);
+            }
+        }
+        const finalServiceUrl = tokenResult.connectionConfig.serviceUrl ||
+            serviceUrl ||
+            serviceKeyServiceUrl;
+        const connectionConfigWithServiceUrl = {
+            ...tokenResult.connectionConfig,
+            serviceUrl: finalServiceUrl,
+        };
+        const authorizationConfig = {
+            ...uaaCredentials,
+            refreshToken: tokenResult.refreshToken || refreshToken,
+        };
+        await this.saveTokenToSession(destination, connectionConfigWithServiceUrl, authorizationConfig);
+        return token;
+    }
+    /**
+     * Refresh token from service key (Step 2b)
+     */
+    async refreshTokenFromServiceKey(destination, uaaCredentials, serviceUrl) {
         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.`);
+            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;
         }
+        this.logger?.debug(`Step 2b: Trying refreshTokenFromServiceKey for ${destination}`);
+        let tokenResult;
         try {
-            this.logger?.debug(`Step 2b: Trying refreshTokenFromServiceKey for ${destination}`);
-            const tokenResult = await this.tokenProvider.refreshTokenFromServiceKey(uaaCredentials, {
+            tokenResult = await this.tokenProvider.refreshTokenFromServiceKey(uaaCredentials, {
                 browser: this.browser,
                 logger: this.logger,
             });
-            const tokenLength = tokenResult.connectionConfig.authorizationToken?.length || 0;
-            this.logger?.info(`Step 2b: Token refreshed from service key for ${destination}: token(${tokenLength} chars), hasRefreshToken(${!!tokenResult.refreshToken})`);
-            // Get serviceUrl from session or service key
-            let serviceKeyServiceUrl;
-            if (this.serviceKeyStore) {
-                try {
-                    const serviceKeyConn = await this.serviceKeyStore.getConnectionConfig(destination);
-                    serviceKeyServiceUrl = serviceKeyConn?.serviceUrl;
+        }
+        catch (error) {
+            if (hasErrorCode(error)) {
+                if (error.code === 'VALIDATION_ERROR') {
+                    throw new Error(`Token refresh failed: Missing required fields in authConfig - ${error.missingFields?.join(', ')}`);
+                }
+                else if (error.code === 'BROWSER_AUTH_ERROR') {
+                    throw new Error(`Token refresh failed: Browser authentication failed or was cancelled - ${getErrorMessage(error)}`);
                 }
-                catch (error) {
-                    this.logger?.debug(`Could not get serviceUrl from service key store: ${error.message}`);
+                else if (error.code === 'ECONNREFUSED' ||
+                    error.code === 'ETIMEDOUT' ||
+                    error.code === 'ENOTFOUND') {
+                    throw new Error(`Token refresh failed: Network error - ${error.code}: Cannot reach authentication server`);
+                }
+                else if (error.code === 'SERVICE_KEY_ERROR') {
+                    throw new Error(`Token refresh failed: Service key not found or invalid for ${destination}`);
                 }
             }
-            const finalServiceUrl = tokenResult.connectionConfig.serviceUrl || serviceUrl || serviceKeyServiceUrl;
-            const connectionConfigWithServiceUrl = {
-                ...tokenResult.connectionConfig,
-                serviceUrl: finalServiceUrl,
-            };
-            // Update session with new token
+            throw new Error(`Token refresh failed for ${destination}: ${getErrorMessage(error)}`);
+        }
+        const token = tokenResult.connectionConfig.authorizationToken;
+        if (!token) {
+            throw new Error(`Token provider did not return authorization token for destination "${destination}"`);
+        }
+        const tokenLength = token.length;
+        this.logger?.info(`Step 2b: Token refreshed from service key for ${destination}: token(${tokenLength} chars), hasRefreshToken(${!!tokenResult.refreshToken})`);
+        // Get serviceUrl from session or service key
+        let serviceKeyServiceUrl;
+        if (this.serviceKeyStore) {
             try {
-                await this.sessionStore.setConnectionConfig(destination, connectionConfigWithServiceUrl);
+                const serviceKeyConn = await this.serviceKeyStore.getConnectionConfig(destination);
+                serviceKeyServiceUrl = serviceKeyConn?.serviceUrl;
             }
             catch (error) {
-                this.logger?.error(`Step 2b: Failed to save connection config to session for ${destination}: ${error.message}`);
-                throw new Error(`Failed to save connection config for destination "${destination}": ${error.message}`);
+                this.logger?.debug(`Could not get serviceUrl from service key store: ${getErrorMessage(error)}`);
+            }
+        }
+        const finalServiceUrl = tokenResult.connectionConfig.serviceUrl ||
+            serviceUrl ||
+            serviceKeyServiceUrl;
+        const connectionConfigWithServiceUrl = {
+            ...tokenResult.connectionConfig,
+            serviceUrl: finalServiceUrl,
+        };
+        const authorizationConfig = {
+            ...uaaCredentials,
+            refreshToken: tokenResult.refreshToken || uaaCredentials.refreshToken,
+        };
+        await this.saveTokenToSession(destination, connectionConfigWithServiceUrl, authorizationConfig);
+        return token;
+    }
+    /**
+     * Get authentication token for destination.
+     * Uses tokenProvider for all authentication operations (browser-based authorization).
+     *
+     * **Flow:**
+     * **Step 0: Initialize Session with Token (if needed)**
+     * - Check if session has `authorizationToken` AND UAA credentials
+     * - If both are empty AND serviceKeyStore is available:
+     *   - Get UAA credentials from service key
+     *   - Use tokenProvider for browser-based authentication
+     *   - Save token and refresh token to session
+     *
+     * **Step 1: Token Validation**
+     * - If token exists in session, validate it (if provider supports validation)
+     * - If valid → return token
+     * - If invalid or no token → continue to refresh
+     *
+     * **Step 2: Refresh Token Flow**
+     * - Check if refresh token exists in session
+     * - If refresh token exists:
+     *   - Use tokenProvider to refresh token (browser-based or refresh grant)
+     *   - Save new token to session
+     *   - Return new token
+     * - Otherwise → proceed to Step 3
+     *
+     * **Step 3: New Token Flow**
+     * - Get UAA credentials from session or service key
+     * - Use tokenProvider for browser-based authentication
+     * - Save new token to session
+     * - Return new token
+     *
+     * **Important Notes:**
+     * - All authentication is handled by tokenProvider (e.g., XSUAA provider)
+     * - Provider uses browser-based authorization to ensure proper role assignment
+     * - Direct UAA HTTP requests are not used to avoid role assignment issues
+     *
+     * @param destination Destination name (e.g., "TRIAL")
+     * @returns Promise that resolves to JWT token string
+     * @throws Error if session initialization fails or authentication failed
+     */
+    async getToken(destination) {
+        this.logger?.debug(`Getting token for destination: ${destination}`);
+        // Load session data
+        const { connConfig, authConfig } = await this.loadSessionData(destination);
+        // Get serviceUrl (required)
+        const serviceUrl = await this.getServiceUrl(destination, connConfig);
+        // Check if we have token or UAA credentials
+        const hasToken = !!connConfig?.authorizationToken;
+        const hasUaaCredentials = !!(authConfig?.uaaUrl &&
+            authConfig?.uaaClientId &&
+            authConfig?.uaaClientSecret);
+        this.logger?.debug(`Session check for ${destination}: hasToken(${hasToken}), hasUaaCredentials(${hasUaaCredentials}), serviceUrl(${serviceUrl ? 'yes' : 'no'})`);
+        // Step 0: Initialize Session with Token (if needed)
+        if (!hasToken && !hasUaaCredentials) {
+            try {
+                return await this.initializeSessionFromServiceKey(destination, serviceUrl);
             }
-            if (tokenResult.refreshToken) {
-                try {
-                    await this.sessionStore.setAuthorizationConfig(destination, {
-                        ...uaaCredentials,
-                        refreshToken: tokenResult.refreshToken,
-                    });
+            catch (error) {
+                // Re-throw BROWSER_AUTH_REQUIRED error without wrapping
+                if (hasErrorCode(error) && error.code === 'BROWSER_AUTH_REQUIRED') {
+                    throw error;
                 }
-                catch (error) {
-                    this.logger?.error(`Step 2b: Failed to save authorization config to session for ${destination}: ${error.message}`);
-                    throw new Error(`Failed to save authorization config for destination "${destination}": ${error.message}`);
+                // Handle typed store errors
+                if (hasErrorCode(error)) {
+                    if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
+                        throw new Error(`Cannot initialize session for destination "${destination}": service key file not found`);
+                    }
+                    else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
+                        throw new Error(`Cannot initialize session for destination "${destination}": service key parsing failed - ${getErrorMessage(error)}`);
+                    }
+                    else if (error.code === interfaces_1.STORE_ERROR_CODES.INVALID_CONFIG) {
+                        throw new Error(`Cannot initialize session for destination "${destination}": invalid service key - missing ${error.missingFields?.join(', ') || 'required fields'}`);
+                    }
                 }
+                throw error;
             }
-            return tokenResult.connectionConfig.authorizationToken;
         }
-        catch (error) {
-            this.logger?.error(`Step 2b: refreshTokenFromServiceKey failed for ${destination}: ${error.message}`);
-            // Determine error cause and throw meaningful error
-            if (error.code === 'VALIDATION_ERROR') {
-                throw new Error(`Token refresh failed: Missing required fields in authConfig - ${error.missingFields?.join(', ')}`);
+        // Step 1: Validate existing token
+        if (hasToken && connConfig?.authorizationToken) {
+            const isValid = await this.validateExistingToken(destination, connConfig.authorizationToken, serviceUrl);
+            if (isValid) {
+                return connConfig.authorizationToken;
             }
-            else if (error.code === 'BROWSER_AUTH_ERROR') {
-                throw new Error(`Token refresh failed: Browser authentication failed or was cancelled - ${error.message}`);
+            // If no validation or validation failed, continue to refresh
+            if (!this.tokenProvider?.validateToken) {
+                this.logger?.info(`Token found for ${destination} (no validation): token(${connConfig.authorizationToken.length} chars)`);
+                return connConfig.authorizationToken;
             }
-            else if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') {
-                throw new Error(`Token refresh failed: Network error - ${error.code}: Cannot reach authentication server`);
+        }
+        // Step 2: Refresh Token Flow
+        this.logger?.debug(`Step 2: Attempting token refresh for ${destination}`);
+        const uaaCredentials = await this.getUaaCredentials(destination, authConfig);
+        // Step 2a: Try refresh from session (if refresh token exists)
+        const refreshToken = authConfig?.refreshToken;
+        if (refreshToken) {
+            try {
+                return await this.refreshTokenFromSession(destination, uaaCredentials, refreshToken, serviceUrl);
             }
-            else if (error.code === 'SERVICE_KEY_ERROR') {
-                throw new Error(`Token refresh failed: Service key not found or invalid for ${destination}`);
+            catch (error) {
+                this.logger?.debug(`Step 2a: refreshTokenFromSession failed for ${destination}: ${getErrorMessage(error)}, trying refreshTokenFromServiceKey`);
+                // Continue to try service key refresh
             }
-            // Generic error
-            throw new Error(`Token refresh failed for ${destination}: ${error.message}`);
         }
+        else {
+            this.logger?.debug(`Step 2a: No refresh token in session for ${destination}, skipping to service key refresh`);
+        }
+        // Step 2b: Try refresh from service key (browser authentication)
+        return await this.refreshTokenFromServiceKey(destination, uaaCredentials, serviceUrl);
     }
     /**
      * Force refresh token for destination.
@@ -521,10 +596,11 @@ class AuthBroker {
         this.logger?.debug(`Checking session store for authorization config: ${destination}`);
         let sessionAuthConfig = null;
         try {
-            sessionAuthConfig = await this.sessionStore.getAuthorizationConfig(destination);
+            sessionAuthConfig =
+                await this.sessionStore.getAuthorizationConfig(destination);
         }
         catch (error) {
-            this.logger?.warn(`Failed to get authorization config from session store for ${destination}: ${error.message}`);
+            this.logger?.warn(`Failed to get authorization config from session store for ${destination}: ${getErrorMessage(error)}`);
         }
         if (sessionAuthConfig) {
             this.logger?.debug(`Authorization config from session for ${destination}: hasUaaUrl(${!!sessionAuthConfig.uaaUrl}), hasRefreshToken(${!!sessionAuthConfig.refreshToken})`);
@@ -535,18 +611,24 @@ class AuthBroker {
             this.logger?.debug(`Checking service key store for authorization config: ${destination}`);
             let serviceKeyAuthConfig = null;
             try {
-                serviceKeyAuthConfig = await this.serviceKeyStore.getAuthorizationConfig(destination);
+                serviceKeyAuthConfig =
+                    await this.serviceKeyStore.getAuthorizationConfig(destination);
             }
             catch (error) {
                 // Handle typed store errors
-                if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
-                    this.logger?.debug(`Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
-                }
-                else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
-                    this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${error.message}`);
+                if (hasErrorCode(error)) {
+                    if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
+                        this.logger?.debug(`Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
+                    }
+                    else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
+                        this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${getErrorMessage(error)}`);
+                    }
+                    else {
+                        this.logger?.warn(`Failed to get authorization config from service key store for ${destination}: ${getErrorMessage(error)}`);
+                    }
                 }
                 else {
-                    this.logger?.warn(`Failed to get authorization config from service key store for ${destination}: ${error.message}`);
+                    this.logger?.warn(`Failed to get authorization config from service key store for ${destination}: ${getErrorMessage(error)}`);
                 }
             }
             if (serviceKeyAuthConfig) {
@@ -570,10 +652,11 @@ class AuthBroker {
         // Try session store first (has tokens and URLs)
         let sessionConnConfig = null;
         try {
-            sessionConnConfig = await this.sessionStore.getConnectionConfig(destination);
+            sessionConnConfig =
+                await this.sessionStore.getConnectionConfig(destination);
         }
         catch (error) {
-            this.logger?.warn(`Failed to get connection config from session store for ${destination}: ${error.message}`);
+            this.logger?.warn(`Failed to get connection config from session store for ${destination}: ${getErrorMessage(error)}`);
         }
         if (sessionConnConfig) {
             this.logger?.debug(`Connection config from session for ${destination}: token(${sessionConnConfig.authorizationToken?.length || 0} chars), serviceUrl(${sessionConnConfig.serviceUrl ? 'yes' : 'no'})`);
@@ -583,18 +666,24 @@ class AuthBroker {
         if (this.serviceKeyStore) {
             let serviceKeyConnConfig = null;
             try {
-                serviceKeyConnConfig = await this.serviceKeyStore.getConnectionConfig(destination);
+                serviceKeyConnConfig =
+                    await this.serviceKeyStore.getConnectionConfig(destination);
             }
             catch (error) {
                 // Handle typed store errors
-                if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
-                    this.logger?.debug(`Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
-                }
-                else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
-                    this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${error.message}`);
+                if (hasErrorCode(error)) {
+                    if (error.code === interfaces_1.STORE_ERROR_CODES.FILE_NOT_FOUND) {
+                        this.logger?.debug(`Service key file not found for ${destination}: ${error.filePath || 'unknown path'}`);
+                    }
+                    else if (error.code === interfaces_1.STORE_ERROR_CODES.PARSE_ERROR) {
+                        this.logger?.warn(`Failed to parse service key for ${destination}: ${error.filePath || 'unknown path'} - ${getErrorMessage(error)}`);
+                    }
+                    else {
+                        this.logger?.warn(`Failed to get connection config from service key store for ${destination}: ${getErrorMessage(error)}`);
+                    }
                 }
                 else {
-                    this.logger?.warn(`Failed to get connection config from service key store for ${destination}: ${error.message}`);
+                    this.logger?.warn(`Failed to get connection config from service key store for ${destination}: ${getErrorMessage(error)}`);
                 }
             }
             if (serviceKeyConnConfig) {
@@ -608,5 +697,41 @@ class AuthBroker {
         this.logger?.debug(`No connection config found for ${destination}`);
         return null;
     }
+    /**
+     * Create a token refresher for a specific destination.
+     *
+     * The token refresher is designed to be injected into JwtAbapConnection via DI,
+     * allowing the connection to handle token refresh transparently without knowing
+     * about authentication internals.
+     *
+     * **Usage:**
+     * ```typescript
+     * const broker = new AuthBroker(config);
+     * const tokenRefresher = broker.createTokenRefresher('TRIAL');
+     * const connection = new JwtAbapConnection(config, tokenRefresher);
+     * ```
+     *
+     * @param destination Destination name (e.g., "TRIAL")
+     * @returns ITokenRefresher implementation for the given destination
+     */
+    createTokenRefresher(destination) {
+        const broker = this;
+        return {
+            /**
+             * Get current valid token.
+             * Returns cached token if valid, otherwise refreshes and returns new token.
+             */
+            async getToken() {
+                return broker.getToken(destination);
+            },
+            /**
+             * Force refresh token and save to session store.
+             * Always performs refresh, ignoring cached token validity.
+             */
+            async refreshToken() {
+                return broker.refreshToken(destination);
+            },
+        };
+    }
 }
 exports.AuthBroker = AuthBroker;