@mcp-abap-adt/auth-broker 0.1.11 → 0.2.1

package/CHANGELOG.md

@@ -11,6 +11,164 @@ Thank you to all contributors! See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the co
 
 ## [Unreleased]
 
+## [0.2.1] - 2025-12-12
+
+### Fixed
+- **ServiceUrl fallback from serviceKeyStore**: Fixed `getToken()` method to retrieve `serviceUrl` from `serviceKeyStore` when it's missing in session
+  - Previously, `getToken()` would throw an error immediately if `serviceUrl` was not found in session, even when it was available in `serviceKeyStore`
+  - Now, the method first checks session for `serviceUrl`, and if not found, attempts to retrieve it from `serviceKeyStore` before throwing an error
+  - This allows integration tests and real-world scenarios to work correctly when session is empty but service key contains `serviceUrl`
+  - Error messages now indicate that `serviceUrl` can come from either session or `serviceKeyStore`
+
+## [0.2.0] - 2025-12-08
+
+### Breaking Changes
+
+**⚠️ IMPORTANT: This is a breaking change with NO backward compatibility. Migration is required. See Migration Guide below.**
+
+#### Constructor Signature Changed
+- **Constructor now accepts configuration object**: The constructor signature has changed from requiring all three dependencies to making `serviceKeyStore` and `tokenProvider` optional
+- **No backward compatibility**: Old constructor signature is NOT supported. You must update your code to use the new signature. Migration guide provided below.
+  - **Before (v0.1.x)**:
+    ```typescript
+    new AuthBroker({
+      serviceKeyStore: serviceKeyStore,  // required
+      sessionStore: sessionStore,         // required
+      tokenProvider: tokenProvider,      // required
+    }, browser?, logger?)
+    ```
+  - **After (v0.2.0)**:
+    ```typescript
+    new AuthBroker({
+      sessionStore: sessionStore,         // required
+      serviceKeyStore?: serviceKeyStore,  // optional
+      tokenProvider?: tokenProvider,      // optional
+    }, browser?, logger?)
+    ```
+
+#### New Authentication Flow
+- **Three-step authentication flow**: `getToken()` now implements a new three-step flow (Step 0, Step 1, Step 2) instead of the previous six-step fallback chain
+- **Direct UAA HTTP requests**: When UAA credentials are available in session, broker uses direct HTTP requests to UAA without requiring `tokenProvider`
+- **Session initialization requirements**: SessionStore must contain initial session with `serviceUrl` before calling `getToken()`
+
+### Added
+
+#### Direct UAA HTTP Requests
+- **Direct UAA refresh_token grant**: When UAA credentials are available in session, broker can refresh tokens directly via HTTP without `tokenProvider`
+- **Direct UAA client_credentials grant**: When UAA credentials are available, broker can obtain tokens directly via HTTP without `tokenProvider`
+- **Automatic fallback to provider**: If direct UAA requests fail and `tokenProvider` is available, broker automatically falls back to provider
+
+#### Flexible Configuration
+- **Optional serviceKeyStore**: `serviceKeyStore` is now optional - only needed for initializing sessions from service keys
+- **Optional tokenProvider**: `tokenProvider` is now optional - only needed for browser authentication or when direct UAA requests fail
+- **Session-only mode**: Can work with only `sessionStore` if session contains valid UAA credentials (no `serviceKeyStore` or `tokenProvider` needed)
+
+#### Enhanced Error Messages
+- **Step-based error messages**: Error messages now indicate which step failed (Step 0, Step 1, or Step 2)
+- **Context-aware errors**: Error messages include information about what was tried and what's available
+- **Actionable errors**: Error messages suggest what to do next (e.g., "Provide serviceKeyStore to initialize from service key")
+
+### Changed
+
+#### Authentication Flow (getToken)
+- **Step 0: Session Initialization**: 
+  - Checks if session has `authorizationToken` and UAA credentials
+  - If both empty and `serviceKeyStore` available: tries direct UAA request from service key, falls back to provider if failed
+  - If session has token OR UAA credentials → proceeds to Step 1
+- **Step 1: Refresh Token Flow**:
+  - If refresh token exists: tries direct UAA refresh, falls back to provider if failed
+  - If successful → returns new token
+  - Otherwise → proceeds to Step 2
+- **Step 2: UAA Credentials Flow**:
+  - Tries direct UAA client_credentials request, falls back to provider if failed
+  - If successful → returns new token
+  - If all failed → throws error
+
+#### Token Refresh (refreshToken)
+- **Direct UAA support**: Uses direct UAA HTTP requests when UAA credentials are available
+- **Provider fallback**: Falls back to provider if direct UAA fails and provider is available
+
+#### Dependencies
+- **Added axios**: Added `axios@^1.13.2` as dependency for direct UAA HTTP requests
+- **Updated interfaces**: Works with `@mcp-abap-adt/interfaces@^0.1.4+`
+
+### Migration Guide
+
+#### Updating Constructor Calls
+
+**Before (v0.1.x)**:
+```typescript
+const broker = new AuthBroker({
+  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']),
+  sessionStore: new AbapSessionStore(['/path/to/destinations']),
+  tokenProvider: new BtpTokenProvider(),
+}, 'chrome', logger);
+```
+
+**After (v0.2.0) - All dependencies**:
+```typescript
+const broker = new AuthBroker({
+  sessionStore: new AbapSessionStore(['/path/to/destinations']),
+  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']), // optional
+  tokenProvider: new BtpTokenProvider(), // optional
+}, 'chrome', logger);
+```
+
+**After (v0.2.0) - Session only (if session has UAA credentials)**:
+```typescript
+const broker = new AuthBroker({
+  sessionStore: new AbapSessionStore(['/path/to/destinations']),
+  // serviceKeyStore and tokenProvider not needed if session has UAA credentials
+});
+```
+
+**After (v0.2.0) - Session + Service Key (for initialization)**:
+```typescript
+const broker = new AuthBroker({
+  sessionStore: new AbapSessionStore(['/path/to/destinations']),
+  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']),
+  // tokenProvider optional - direct UAA requests will be used
+});
+```
+
+#### Session Requirements
+
+**Important**: SessionStore must contain initial session with `serviceUrl` before calling `getToken()`. If session is empty, provide `serviceKeyStore` to initialize from service key.
+
+#### When to Provide tokenProvider
+
+- **Required**: When initializing session from service key via browser authentication (Step 0)
+- **Optional but recommended**: As fallback when direct UAA requests fail
+- **Not needed**: When session contains valid UAA credentials (direct UAA requests will be used)
+
+### Dependencies
+- Updated to work with `@mcp-abap-adt/connection` v0.2.0+ (which removed token refresh and session storage)
+- Updated to work with `@mcp-abap-adt/interfaces` v0.1.4+ (which removed session state methods from `IAbapConnection`)
+- Added `axios@^1.13.2` for direct UAA HTTP requests
+
+## [0.1.12] - 2025-12-09
+
+### Added
+- **Debugging Environment Variables**: Added comprehensive debugging support via environment variables
+  - `DEBUG_AUTH_BROKER` - Enable/disable logging for auth-broker package (default: `false`)
+  - `LOG_LEVEL` - Control log verbosity: `debug`, `info`, `warn`, `error` (default: `info`)
+  - `DEBUG` - Alternative way to enable debugging (set to `true` or string containing `auth-broker`)
+  - Logging is disabled by default to avoid misleading output in tests
+  - Tests that expect errors use no-op logger to prevent error message output
+
+### Changed
+- **Test Logger Behavior**: Modified `createTestLogger` to require explicit enable via environment variables
+  - No longer enabled by default in test environment (`NODE_ENV === 'test'`)
+  - Requires `DEBUG_AUTH_BROKER=true` or `DEBUG=true` to enable logging
+  - Prevents misleading error output in tests that expect errors
+  - Tests that expect errors now use `noOpLogger` to avoid false error messages
+
+### Fixed
+- **Service URL Handling**: Fixed `serviceUrl` propagation for ABAP sessions
+  - `AuthBroker` now retrieves `serviceUrl` from `serviceKeyStore` if not provided by `tokenProvider`
+  - Ensures ABAP session stores receive required `serviceUrl` even when token provider doesn't return it
+  - Applied to all authentication flows (refresh token, UAA, browser auth)
+
 ## [0.1.11] - 2025-12-07
 
 ### Changed

package/README.md

@@ -19,43 +19,84 @@ npm install @mcp-abap-adt/auth-broker
 
 ## Usage
 
+### Basic Usage (Session Only)
+
+If your sessionStore contains valid UAA credentials, you only need to provide `sessionStore`:
+
+```typescript
+import { AuthBroker, AbapSessionStore } from '@mcp-abap-adt/auth-broker';
+
+// Session-only mode - works if session has UAA credentials
+const broker = new AuthBroker({
+  sessionStore: new AbapSessionStore('/path/to/destinations'),
+});
+
+// Get token - uses direct UAA HTTP requests automatically
+const token = await broker.getToken('TRIAL');
+```
+
+### Full Configuration (All Dependencies)
+
+For maximum flexibility, provide all three dependencies:
+
 ```typescript
 import { 
   AuthBroker, 
   AbapServiceKeyStore, 
   AbapSessionStore, 
-  SafeAbapSessionStore,
   BtpTokenProvider
 } from '@mcp-abap-adt/auth-broker';
 
-// Use default file-based stores (current working directory)
-const broker = new AuthBroker();
+const broker = new AuthBroker({
+  sessionStore: new AbapSessionStore('/path/to/destinations'),
+  serviceKeyStore: new AbapServiceKeyStore('/path/to/destinations'), // optional
+  tokenProvider: new BtpTokenProvider(), // optional
+}, 'chrome', logger);
+```
+
+### Session + Service Key (For Initialization)
 
-// Use custom file-based stores with specific paths
+If you need to initialize sessions from service keys:
+
+```typescript
 const broker = new AuthBroker({
-  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']),
-  sessionStore: new AbapSessionStore(['/path/to/destinations']),
-  tokenProvider: new BtpTokenProvider(),
-}, 'chrome');
+  sessionStore: new AbapSessionStore('/path/to/destinations'),
+  serviceKeyStore: new AbapServiceKeyStore('/path/to/destinations'),
+  // tokenProvider optional - direct UAA requests will be used from service key
+});
+```
+
+### In-Memory Session Store
+
+For testing or temporary sessions:
+
+```typescript
+import { AuthBroker, SafeAbapSessionStore } from '@mcp-abap-adt/auth-broker';
 
-// Use safe in-memory session store (data lost after restart)
 const broker = new AuthBroker({
-  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']),
-  sessionStore: new SafeAbapSessionStore(), // In-memory, secure
-  tokenProvider: new BtpTokenProvider(),
+  sessionStore: new SafeAbapSessionStore(), // In-memory, data lost after restart
 });
+```
+
+### Custom Browser Auth Port
 
-// Use BtpTokenProvider with custom browser auth port (to avoid port conflicts)
-const brokerWithCustomPort = new AuthBroker({
-  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']),
-  sessionStore: new AbapSessionStore(['/path/to/destinations']),
+To avoid port conflicts with browser authentication:
+
+```typescript
+const broker = new AuthBroker({
+  sessionStore: new AbapSessionStore('/path/to/destinations'),
+  serviceKeyStore: new AbapServiceKeyStore('/path/to/destinations'),
   tokenProvider: new BtpTokenProvider(4001), // Custom port for OAuth callback server
-});
+}, 'chrome');
+```
+
+### Getting Tokens
 
-// Get token for destination (loads from .env, validates, refreshes if needed)
+```typescript
+// Get token - automatically uses direct UAA requests if UAA credentials available
 const token = await broker.getToken('TRIAL');
 
-// Force refresh token using service key
+// Force refresh token
 const newToken = await broker.refreshToken('TRIAL');
 ```
 
@@ -63,8 +104,36 @@ const newToken = await broker.refreshToken('TRIAL');
 
 ### Environment Variables
 
+#### Configuration Variables
+
 - `AUTH_BROKER_PATH` - Colon/semicolon-separated paths for searching `.env` and `.json` files (default: current working directory)
-- `DEBUG_AUTH_LOG` - Set to `true` to enable debug logging (default: `false`)
+
+#### Debugging Variables
+
+- `DEBUG_AUTH_BROKER` - Enable debug logging for `auth-broker` package
+  - Set to `true` to enable logging (default: `false`)
+  - When enabled, logs authentication steps, token operations, and error details
+  - Can be explicitly disabled by setting to `false`
+  - Example: `DEBUG_AUTH_BROKER=true npm test`
+  
+- `LOG_LEVEL` - Control log verbosity level
+  - Values: `debug`, `info`, `warn`, `error` (default: `info`)
+  - `debug` - All messages including detailed debug information
+  - `info` - Informational messages, warnings, and errors
+  - `warn` - Warnings and errors only
+  - `error` - Errors only
+  - Example: `LOG_LEVEL=debug DEBUG_AUTH_BROKER=true npm test`
+
+- `DEBUG` - Alternative way to enable debugging
+  - Set to `true` to enable all debug logging
+  - Or set to a string containing `auth-broker` to enable only this package
+  - Example: `DEBUG=true npm test` or `DEBUG=auth-broker npm test`
+
+**Note**: For debugging related packages:
+- `DEBUG_AUTH_STORES` - Enable logging for `@mcp-abap-adt/auth-stores` package
+- `DEBUG_AUTH_PROVIDERS` - Enable logging for `@mcp-abap-adt/auth-providers` package
+
+**Legacy Support**: `DEBUG_AUTH_LOG` is still supported for backward compatibility (equivalent to `DEBUG_AUTH_BROKER=true LOG_LEVEL=debug`)
 
 ### File Structure
 
@@ -274,45 +343,83 @@ Instead, the consumer or `AbapSessionStore` itself should handle this:
 
 ```typescript
 new AuthBroker(
-  stores?: { 
-    serviceKeyStore?: IServiceKeyStore; 
-    sessionStore?: ISessionStore;
-    tokenProvider?: ITokenProvider;
+  config: {
+    sessionStore: ISessionStore;        // required
+    serviceKeyStore?: IServiceKeyStore; // optional
+    tokenProvider?: ITokenProvider;      // optional
   }, 
   browser?: string, 
   logger?: ILogger
 )
 ```
 
-- `stores` - Optional object with custom storage implementations:
-  - `serviceKeyStore` - Store for service keys (default: `AbapServiceKeyStore()`)
-  - `sessionStore` - Store for session data (default: `AbapSessionStore()`)
-  - `tokenProvider` - Token provider for token acquisition (default: `BtpTokenProvider()`)
-  - Available implementations:
-    - **ABAP**: `AbapServiceKeyStore(searchPaths?)`, `AbapSessionStore(searchPaths?)`, `SafeAbapSessionStore()`, `BtpTokenProvider()`
-    - **XSUAA** (reduced scope): `XsuaaServiceKeyStore(searchPaths?)`, `XsuaaSessionStore(searchPaths?)`, `SafeXsuaaSessionStore()`, `XsuaaTokenProvider()`
-    - **BTP** (full scope for ABAP): `AbapServiceKeyStore(searchPaths?)`, `BtpSessionStore(searchPaths?)`, `SafeBtpSessionStore()`, `BtpTokenProvider()`
+**Parameters:**
+- `config` - Configuration object:
+  - `sessionStore` - **Required** - Store for session data. Must contain initial session with `serviceUrl`
+  - `serviceKeyStore` - **Optional** - Store for service keys. Only needed for initializing sessions from service keys
+  - `tokenProvider` - **Optional** - Token provider for token acquisition. Only needed for browser authentication or when direct UAA requests fail
 - `browser` - Optional browser name for authentication (`chrome`, `edge`, `firefox`, `system`, `none`). Default: `system`
   - For XSUAA, browser is not used (client_credentials grant type) - use `'none'`
-- `logger` - Optional logger instance. If not provided, uses default logger
+- `logger` - Optional logger instance. If not provided, uses no-op logger
 
-#### Methods
+**When to Provide Each Dependency:**
 
-##### `getToken(destination: string): Promise<string>`
+- **`sessionStore` (required)**: Always required. Must contain initial session with `serviceUrl`
+- **`serviceKeyStore` (optional)**: 
+  - Required if you need to initialize sessions from service keys (Step 0)
+  - Not needed if session already contains UAA credentials
+- **`tokenProvider` (optional)**:
+  - Required for browser authentication when initializing from service key (Step 0)
+  - Optional but recommended as fallback when direct UAA requests fail
+  - Not needed if session contains valid UAA credentials (direct UAA HTTP requests will be used)
+
+**Available Implementations:**
+- **ABAP**: `AbapServiceKeyStore(directory, defaultServiceUrl?, logger?)`, `AbapSessionStore(directory, defaultServiceUrl?, logger?)`, `SafeAbapSessionStore(defaultServiceUrl?, logger?)`, `BtpTokenProvider(browserAuthPort?)`
+- **XSUAA** (reduced scope): `XsuaaServiceKeyStore(directory, logger?)`, `XsuaaSessionStore(directory, defaultServiceUrl, logger?)`, `SafeXsuaaSessionStore(defaultServiceUrl, logger?)`, `XsuaaTokenProvider()`
+- **BTP** (full scope for ABAP): `AbapServiceKeyStore(directory, defaultServiceUrl?, logger?)`, `BtpSessionStore(directory, defaultServiceUrl, logger?)`, `SafeBtpSessionStore(defaultServiceUrl, logger?)`, `BtpTokenProvider(browserAuthPort?)`
 
-Gets authentication token for destination. Tries to load from session store, validates it, and refreshes if needed using a fallback chain:
+#### Methods
 
-1. **Check session**: Load token from session store and validate it
-2. **Try refresh token**: If refresh token is available, attempt to refresh using it (via tokenProvider)
-3. **Try UAA (client_credentials)**: Attempt to get token using UAA credentials (via tokenProvider)
-4. **Try browser authentication**: Attempt browser-based OAuth2 flow using service key (via tokenProvider)
-5. **Throw error**: If all authentication methods failed
+##### `getToken(destination: string): Promise<string>`
 
-**Note**: Token validation is performed only when checking existing session. Tokens obtained through refresh/UAA/browser authentication are not validated before being saved.
+Gets authentication token for destination. Implements a three-step flow:
+
+**Step 0: Initialize Session with Token (if needed)**
+- Checks if session has `authorizationToken` and UAA credentials
+- If both are empty and `serviceKeyStore` is available:
+  - Tries direct UAA request from service key (if UAA credentials available)
+  - If failed and `tokenProvider` available → uses provider for authentication
+- If session has token OR UAA credentials → proceeds to Step 1
+
+**Step 1: Refresh Token Flow**
+- Checks if refresh token exists in session
+- If refresh token exists:
+  - Tries direct UAA refresh (if UAA credentials in session)
+  - If failed and `tokenProvider` available → uses provider
+  - If successful → returns new token
+- Otherwise → proceeds to Step 2
+
+**Step 2: UAA Credentials Flow**
+- Checks if UAA credentials exist in session or service key
+- Tries direct UAA client_credentials request (if UAA credentials available)
+- If failed and `tokenProvider` available → uses provider
+- If successful → returns new token
+- If all failed → throws error
+
+**Important Notes:**
+- If `sessionStore` contains valid UAA credentials, neither `serviceKeyStore` nor `tokenProvider` are required. Direct UAA HTTP requests will be used automatically.
+- `tokenProvider` is only needed for browser authentication or when direct UAA requests fail.
+- Token validation is performed only when checking existing session. Tokens obtained through refresh/UAA/browser authentication are not validated before being saved.
 
 ##### `refreshToken(destination: string): Promise<string>`
 
-Force refresh token for destination using service key from `{destination}.json` file.
+Force refresh token for destination. Uses refresh token from session if available, otherwise uses UAA credentials from session or service key.
+
+**Flow:**
+- If refresh token exists and UAA credentials available → tries direct UAA refresh
+- If direct UAA fails and `tokenProvider` available → uses provider
+- If no refresh token but UAA credentials available → tries direct UAA client_credentials
+- If all failed → throws error
 
 ##### `clearCache(destination: string): void`
 
@@ -346,24 +453,54 @@ import {
   XsuaaServiceKeyStore,
   XsuaaSessionStore,
   XsuaaTokenProvider,
-  BtpTokenProvider
+  BtpTokenProvider,
+  AbapServiceKeyStore,
+  BtpSessionStore
 } from '@mcp-abap-adt/auth-broker';
 
-// XSUAA authentication (no browser needed)
+// XSUAA authentication - session only (direct UAA requests)
 const xsuaaBroker = new AuthBroker({
-  serviceKeyStore: new XsuaaServiceKeyStore(['/path/to/keys']),
-  sessionStore: new XsuaaSessionStore(['/path/to/sessions']),
-  tokenProvider: new XsuaaTokenProvider(),
+  sessionStore: new XsuaaSessionStore('/path/to/sessions', 'https://mcp.example.com'),
+  // serviceKeyStore and tokenProvider not needed if session has UAA credentials
+});
+
+// XSUAA authentication - with service key initialization
+const xsuaaBrokerWithServiceKey = new AuthBroker({
+  sessionStore: new XsuaaSessionStore('/path/to/sessions', 'https://mcp.example.com'),
+  serviceKeyStore: new XsuaaServiceKeyStore('/path/to/keys'),
+  // tokenProvider optional - direct UAA requests will be used
 }, 'none');
 
-// BTP authentication (browser or refresh token)
+// BTP authentication - session only (direct UAA requests)
 const btpBroker = new AuthBroker({
-  serviceKeyStore: new AbapServiceKeyStore(['/path/to/keys']),
-  sessionStore: new BtpSessionStore(['/path/to/sessions']),
-  tokenProvider: new BtpTokenProvider(),
+  sessionStore: new BtpSessionStore('/path/to/sessions', 'https://abap.example.com'),
+  // serviceKeyStore and tokenProvider not needed if session has UAA credentials
+});
+
+// BTP authentication - with service key and provider (for browser auth)
+const btpBrokerFull = new AuthBroker({
+  sessionStore: new BtpSessionStore('/path/to/sessions', 'https://abap.example.com'),
+  serviceKeyStore: new AbapServiceKeyStore('/path/to/keys'),
+  tokenProvider: new BtpTokenProvider(), // needed for browser authentication
 });
 ```
 
+### Direct UAA HTTP Requests
+
+When UAA credentials are available in session, `AuthBroker` automatically uses direct HTTP requests to UAA without requiring `tokenProvider`:
+
+- **Refresh Token Grant**: Direct HTTP POST to `{uaaUrl}/oauth/token` with `grant_type=refresh_token`
+- **Client Credentials Grant**: Direct HTTP POST to `{uaaUrl}/oauth/token` with `grant_type=client_credentials`
+
+**Benefits:**
+- No dependency on `tokenProvider` when session has UAA credentials
+- Faster token refresh (no provider overhead)
+- Simpler configuration (only `sessionStore` needed)
+
+**Fallback to Provider:**
+- If direct UAA request fails and `tokenProvider` is available, broker automatically falls back to provider
+- Provider is useful for browser authentication or alternative authentication flows
+
 ### Utility Script
 
 Generate `.env` files from service keys:

package/dist/AuthBroker.d.ts

@@ -5,8 +5,16 @@ import { ILogger } from '@mcp-abap-adt/interfaces';
 import { IServiceKeyStore, ISessionStore, IAuthorizationConfig, IConnectionConfig } from './stores/interfaces';
 import { ITokenProvider } from './providers';
 /**
- * AuthBroker manages JWT authentication tokens for destinations
+ * Configuration object for AuthBroker constructor
  */
+export interface AuthBrokerConfig {
+    /** Session store (required) - stores and retrieves session data */
+    sessionStore: ISessionStore;
+    /** Service key store (optional) - stores and retrieves service keys */
+    serviceKeyStore?: IServiceKeyStore;
+    /** Token provider (optional) - handles token refresh and authentication flows. If not provided, direct UAA HTTP requests will be used when UAA credentials are available */
+    tokenProvider?: ITokenProvider;
+}
 export declare class AuthBroker {
     private browser;
     private logger;
@@ -15,57 +23,71 @@ export declare class AuthBroker {
     private tokenProvider;
     /**
      * Create a new AuthBroker instance
-     * @param stores Object with stores and token provider
-     *               - serviceKeyStore: Store for service keys
-     *               - sessionStore: Store for session data
-     *               - tokenProvider: Token provider implementing ITokenProvider interface
+     * @param config Configuration object with stores and token provider
+     *               - sessionStore: Store for session data (required)
+     *               - serviceKeyStore: Store for service keys (optional)
+     *               - tokenProvider: Token provider implementing ITokenProvider interface (optional). If not provided, direct UAA HTTP requests will be used when UAA credentials are available
      * @param browser Optional browser name for authentication (chrome, edge, firefox, system, none).
      *                Default: 'system' (system default browser).
      *                Use 'none' to print URL instead of opening browser.
      * @param logger Optional logger instance implementing ILogger interface. If not provided, uses no-op logger.
      */
-    constructor(stores: {
-        serviceKeyStore: IServiceKeyStore;
-        sessionStore: ISessionStore;
-        tokenProvider: ITokenProvider;
-    }, browser?: string, logger?: ILogger);
+    constructor(config: AuthBrokerConfig, browser?: string, logger?: ILogger);
+    /**
+     * Refresh token using refresh_token grant type (direct UAA HTTP request)
+     * @param refreshToken Refresh token
+     * @param authConfig UAA authorization configuration
+     * @returns Promise that resolves to new tokens
+     */
+    private refreshTokenDirect;
+    /**
+     * Get token using client_credentials grant type (direct UAA HTTP request)
+     * @param authConfig UAA authorization configuration
+     * @returns Promise that resolves to access token
+     */
+    private getTokenWithClientCredentials;
     /**
      * Get authentication token for destination.
-     * Tries to load from session store, validates it, and refreshes if needed using a fallback chain.
-     *
-     * **Fallback Chain:**
-     * 1. **Check session**: Load token from session store and validate it
-     *    - If token is valid, return it immediately
-     *    - If token is invalid or missing, continue to next step
-     *
-     * 2. **Check service key**: Verify that service key exists
-     *    - If no service key found, throw error
-     *
-     * 3. **Try refresh token**: If refresh token is available in session, attempt to refresh using it (via tokenProvider)
-     *    - If successful, save new token to session and return it
-     *    - If failed, continue to next step
+     * Implements a three-step flow: Step 0 (initialize), Step 1 (refresh), Step 2 (UAA).
      *
-     * 4. **Try UAA (client_credentials)**: Attempt to get token using UAA credentials (via tokenProvider)
-     *    - If UAA parameters are available and authentication succeeds, save token to session and return it
-     *    - If failed or parameters missing, continue to next step
+     * **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:
+     *   - Try direct UAA request from service key (if UAA credentials available)
+     *   - If failed and tokenProvider available → use provider
+     * - If session has token OR UAA credentials → proceed to Step 1
      *
-     * 5. **Try browser authentication**: Attempt browser-based OAuth2 flow using service key (via tokenProvider)
-     *    - If successful, save token and refresh token to session and return it
-     *    - If failed, continue to next step
+     * **Step 1: Refresh Token Flow**
+     * - Check if refresh token exists in session
+     * - If refresh token exists:
+     *   - Try direct UAA refresh (if UAA credentials in session)
+     *   - If failed and tokenProvider available → use provider
+     *   - If successful → return new token
+     * - Otherwise → proceed to Step 2
      *
-     * 6. **Throw error**: If all authentication methods failed, throw comprehensive error with details
+     * **Step 2: UAA Credentials Flow**
+     * - Check if UAA credentials exist in session or service key
+     * - Try direct UAA client_credentials request (if UAA credentials available)
+     * - If failed and tokenProvider available → use provider
+     * - If successful → return new token
+     * - If all failed → return error
      *
-     * **Note**: Token validation is performed only when checking existing session (step 1).
-     * Tokens obtained through refresh/UAA/browser authentication are not validated before being saved.
+     * **Important Notes:**
+     * - If sessionStore contains valid UAA credentials, neither serviceKeyStore nor tokenProvider are required.
+     *   Direct UAA HTTP requests will be used automatically.
+     * - tokenProvider is only needed when:
+     *   - Initializing session from service key via browser authentication (Step 0)
+     *   - Direct UAA requests fail and fallback to provider is needed
      *
      * @param destination Destination name (e.g., "TRIAL")
      * @returns Promise that resolves to JWT token string
-     * @throws Error if neither session data nor service key found, or if all authentication methods failed
+     * @throws Error if session initialization fails or all authentication methods failed
      */
     getToken(destination: string): Promise<string>;
     /**
-     * Force refresh token for destination using service key.
-     * If no refresh token exists, starts browser authentication flow.
+     * Force refresh token for destination.
+     * Uses refresh token from session if available, otherwise uses UAA credentials from session or service key.
      * @param destination Destination name (e.g., "TRIAL")
      * @returns Promise that resolves to new JWT token string
      */

package/dist/AuthBroker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC/G,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAY7C;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,eAAe,CAAmB;IAC1C,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAAiB;IAEtC;;;;;;;;;;OAUG;gBAED,MAAM,EAAE;QAAE,eAAe,EAAE,gBAAgB,CAAC;QAAC,YAAY,EAAE,aAAa,CAAC;QAAC,aAAa,EAAE,cAAc,CAAA;KAAE,EACzG,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,OAAO;IAuBlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmIpD;;;;;OAKG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuCxD;;;;OAIG;IACG,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAWvF;;;;OAIG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CAWlF"}
+{"version":3,"file":"AuthBroker.d.ts","sourceRoot":"","sources":["../src/AuthBroker.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAW,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC/G,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAa7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,YAAY,EAAE,aAAa,CAAC;IAC5B,uEAAuE;IACvE,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,4KAA4K;IAC5K,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAcD,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,aAAa,CAA6B;IAElD;;;;;;;;;;OAUG;gBAED,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,OAAO;IAgElB;;;;;OAKG;YACW,kBAAkB;IA4ChC;;;;OAIG;YACW,6BAA6B;IA0C3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0SpD;;;;;OAKG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuFxD;;;;OAIG;IACG,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA2BvF;;;;OAIG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CAyBlF"}