@mcp-abap-adt/auth-broker 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -9,6 +9,250 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Thank you to all contributors! See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the complete list.
 
+## [0.1.7] - 2025-12-04
+
+### Changed
+- **getToken() Fallback Chain** - Improved authentication reliability with multi-step fallback chain
+  - **Step 1**: Check if session exists and token is valid (returns immediately if valid)
+  - **Step 2**: Verify service key exists (throws error if missing)
+  - **Step 3**: Try refresh token authentication (via tokenProvider) if refresh token is available
+  - **Step 4**: Try UAA client_credentials authentication (via tokenProvider) if refresh token missing or failed
+  - **Step 5**: Try browser authentication (via tokenProvider) if UAA failed or parameters missing
+  - **Step 6**: Throw comprehensive error if all methods failed
+  - All authentication attempts use `ITokenProvider` interface (no direct implementation imports)
+  - Token validation is performed only when checking existing session (step 1)
+  - Tokens obtained through refresh/UAA/browser authentication are not validated before being saved
+  - Improved error messages with details about which authentication methods failed
+
+## [0.1.6] - 2025-12-04
+
+### Changed
+- **Package Split** - Extracted store and provider implementations into separate packages
+  - `@mcp-abap-adt/auth-stores-btp` - BTP and ABAP stores
+  - `@mcp-abap-adt/auth-stores-xsuaa` - XSUAA stores
+  - `@mcp-abap-adt/auth-providers` - XSUAA and BTP token providers
+  - `auth-broker` now only contains interfaces and core broker logic
+- **ITokenProvider Interface** - Added optional `validateToken` method to token provider interface
+  - Token validation is now handled by providers, not by auth-broker
+  - Providers can implement custom validation logic
+- **Dependencies** - Removed unused dependencies (axios, express, open, dotenv)
+  - These are now in provider/store packages
+  - `auth-broker` only depends on `@mcp-abap-adt/connection`
+
+### Removed
+- Store implementations (moved to `@mcp-abap-adt/auth-stores-btp` and `@mcp-abap-adt/auth-stores-xsuaa`)
+- Provider implementations (moved to `@mcp-abap-adt/auth-providers`)
+- Token validator utility (moved to providers)
+- Authentication functions (moved to providers)
+
+## [0.1.5] - 2025-12-03
+
+### Changed
+- **Interface Naming** - All interfaces now start with `I` prefix
+  - `AuthorizationConfig` → `IAuthorizationConfig`
+  - `ConnectionConfig` → `IConnectionConfig`
+  - `ServiceKeyStore` → `IServiceKeyStore`
+  - `SessionStore` → `ISessionStore`
+- **Type System** - Introduced `IConfig` as optional composition of `IAuthorizationConfig` and `IConnectionConfig`
+  - `loadSession()` and `getServiceKey()` now return `IConfig | null`
+  - `IConfig` is `Partial<IAuthorizationConfig> & Partial<IConnectionConfig>`
+- **Token Provider Architecture** - Extracted token acquisition logic into `ITokenProvider` interface
+  - `XsuaaTokenProvider` - Uses client_credentials grant type (no browser)
+  - `BtpTokenProvider` - Uses browser-based OAuth2 or refresh token
+  - `AuthBroker` now accepts `tokenProvider` in constructor
+- **XSUAA Configuration** - Renamed `btp_url` to `mcp_url` in YAML configuration
+  - For XSUAA, MCP URL is provided via `mcp_url` in YAML config (not `btp_url`)
+  - MCP URL is optional and not part of authentication
+- **Constants** - Removed constants from exports (internal implementation details)
+  - All file operations are handled by stores through interfaces
+  - Consumers should use `IServiceKeyStore` and `ISessionStore` methods
+- **File Structure** - Organized source code into logical subfolders
+  - `src/auth/` - Authentication logic (browserAuth, clientCredentialsAuth, tokenRefresher, tokenValidator)
+  - `src/cache/` - Token caching
+  - `src/constants/` - Internal constants
+  - `src/loaders/` - Service key loaders (abap, xsuaa)
+  - `src/logger/` - Logging utilities
+  - `src/methods/` - AuthBroker methods (getToken, refreshToken)
+  - `src/parsers/` - Service key parsers
+  - `src/pathResolver/` - Path resolution utilities
+  - `src/providers/` - Token providers (ITokenProvider, XsuaaTokenProvider, BtpTokenProvider)
+  - `src/storage/` - Environment file loaders and token storage (abap, btp, xsuaa)
+  - `src/stores/` - Store implementations (abap, btp, xsuaa)
+  - `src/types/` - Type definitions
+  - `src/utils/` - Utility functions
+- **Test Structure** - Organized tests into subfolders by implementation
+  - `src/__tests__/broker/` - AuthBroker tests
+  - `src/__tests__/stores/abap/`, `src/__tests__/stores/btp/`, `src/__tests__/stores/xsuaa/` - Store tests
+  - `src/__tests__/loaders/abap/`, `src/__tests__/loaders/xsuaa/` - Loader tests
+  - `src/__tests__/storage/abap/`, `src/__tests__/storage/btp/`, `src/__tests__/storage/xsuaa/` - Storage tests
+  - `src/__tests__/parsers/` - Parser tests
+  - `src/__tests__/utils/` - Utility tests
+  - `src/__tests__/helpers/` - Test helpers (configHelpers, testHelpers, AuthBrokerTestHelper)
+
+### Removed
+- **ServiceKey Type** - Removed `ServiceKey` type (internal implementation detail)
+- **Internal Types** - Removed internal storage types from exports
+  - `EnvConfig`, `XsuaaSessionConfig`, `BtpSessionConfig` are now internal to store implementations
+- **Constants Export** - Removed constants from public API
+  - `ABAP_AUTHORIZATION_VARS`, `ABAP_CONNECTION_VARS`, etc. are internal
+  - `ABAP_HEADERS`, `XSUAA_HEADERS`, `BTP_HEADERS` are internal
+- **Parser Exports** - Removed parser interfaces and implementations from exports
+  - `IServiceKeyParser`, `AbapServiceKeyParser`, `XsuaaServiceKeyParser` are internal
+
+### Fixed
+- **Test Configuration** - Tests now use YAML configuration file (`tests/test-config.yaml`)
+  - Removed hardcoded paths and destinations
+  - Added `AuthBrokerTestHelper` for creating broker instances from YAML
+  - Tests organized into subfolders by implementation (`abap`, `btp`, `xsuaa`)
+- **Browser Authentication** - Fixed hanging tests when `browser: 'none'` is specified
+  - `startBrowserAuth` now immediately throws error with URL when `browser: 'none'`
+  - Added timeout to `clientCredentialsAuth` to prevent hanging
+- **Session Store Validation** - Fixed validation in `Safe*SessionStore` classes
+  - Now accepts `IConfig` format (with `serviceUrl`/`authorizationToken`) and converts to internal format
+  - Validation messages updated to match actual error messages
+- **YAML Configuration** - Fixed path resolution for test configuration
+  - Uses `findProjectRoot()` to reliably locate `test-config.yaml`
+  - Properly expands `~` to home directory in paths
+  - Added diagnostic logging controlled by `TEST_VERBOSE` environment variable
+
+### Added
+- **BTP Full-Scope Authentication** - Full support for BTP authentication to ABAP systems (with full roles and scopes)
+  - `BtpSessionStore` - Store for BTP sessions (uses `BTP_*` environment variables)
+  - `SafeBtpSessionStore` - In-memory BTP session store
+  - `BtpSessionConfig` - Configuration interface for BTP authentication (includes `abapUrl`)
+  - `loadBtpEnvFile()` - Loads BTP session configuration from `.env` files with `BTP_*` variables
+  - `saveBtpTokenToEnv()` - Saves BTP session configuration to `.env` files with `BTP_*` variables
+- **BTP Environment Variables** - `BTP_ENV_VARS` constants
+  - `BTP_ABAP_URL` - ABAP system URL (required, from service key or YAML)
+  - `BTP_JWT_TOKEN` - JWT token for `Authorization: Bearer` header
+  - `BTP_REFRESH_TOKEN` - Optional refresh token
+  - `BTP_UAA_URL`, `BTP_UAA_CLIENT_ID`, `BTP_UAA_CLIENT_SECRET` - UAA credentials (from service key)
+- **BTP HTTP Headers** - `BTP_HEADERS` constants
+  - `BTP_HEADERS.AUTHORIZATION` - Authorization header
+  - `BTP_HEADERS.ABAP_URL` - ABAP URL header (`x-abap-url`)
+  - `BTP_HEADERS.BTP_DESTINATION` - BTP destination header (`x-btp-destination`)
+  - `BTP_HEADERS.SAP_CLIENT` - SAP client header (`x-sap-client`)
+  - `BTP_HEADERS.LANGUAGE` - Language header (`x-sap-language`)
+- **Helper Functions** - `isBtpEnvVar()` function to check if environment variable is BTP-related
+- **XSUAA Support** - Full support for XSUAA authentication (reduced scope)
+  - `XsuaaServiceKeyStore` - Store for XSUAA service keys (direct format from BTP)
+  - `XsuaaSessionStore` - Store for XSUAA sessions (uses `XSUAA_*` environment variables)
+  - `SafeXsuaaSessionStore` - In-memory XSUAA session store
+  - `XsuaaServiceKeyParser` - Parser for direct XSUAA service key format
+  - Client credentials grant type for XSUAA (no browser required)
+- **Environment Variable Constants** - Exported constants for consumers
+  - `ABAP_ENV_VARS` - Environment variable names for ABAP connections (SAP_URL, SAP_JWT_TOKEN, etc.)
+  - `XSUAA_ENV_VARS` - Environment variable names for XSUAA connections (XSUAA_MCP_URL, XSUAA_JWT_TOKEN, etc.)
+  - `ABAP_HEADERS` - HTTP header names for ABAP requests (x-sap-url, x-sap-jwt-token, etc.)
+  - `XSUAA_HEADERS` - HTTP header names for XSUAA requests (Authorization, x-mcp-url, etc.)
+  - Helper functions: `getBtpAuthorizationHeader()`, `isAbapEnvVar()`, `isXsuaaEnvVar()`
+- **Service Key Parsers** - Modular parser architecture
+  - `IServiceKeyParser` - Interface for service key parsers
+  - `AbapServiceKeyParser` - Parser for standard ABAP service keys
+  - `XsuaaServiceKeyParser` - Parser for direct XSUAA service keys
+- **Utility Script** - `generate-env` command
+  - Generates `.env` files from service keys
+  - Supports both ABAP and XSUAA service key formats
+  - Automatically detects service key type and uses appropriate authentication flow
+- **XSUAA Environment Loader** - `loadXsuaaEnvFile()` function
+  - Loads XSUAA session configuration from `.env` files with `XSUAA_*` variables
+- **XSUAA Token Storage** - `saveXsuaaTokenToEnv()` function
+  - Saves XSUAA session configuration to `.env` files with `XSUAA_*` variables
+  - Automatically removes old `SAP_*` variables when saving XSUAA sessions
+
+### Changed
+- **Interface Naming** - All interfaces now start with `I` prefix
+  - `AuthorizationConfig` → `IAuthorizationConfig`
+  - `ConnectionConfig` → `IConnectionConfig`
+  - `ServiceKeyStore` → `IServiceKeyStore`
+  - `SessionStore` → `ISessionStore`
+- **Type System** - Introduced `IConfig` as optional composition of `IAuthorizationConfig` and `IConnectionConfig`
+  - `loadSession()` and `getServiceKey()` now return `IConfig | null`
+  - `IConfig` is `Partial<IAuthorizationConfig> & Partial<IConnectionConfig>`
+- **Token Provider Architecture** - Extracted token acquisition logic into `ITokenProvider` interface
+  - `XsuaaTokenProvider` - Uses client_credentials grant type (no browser)
+  - `BtpTokenProvider` - Uses browser-based OAuth2 or refresh token
+  - `AuthBroker` now accepts `tokenProvider` in constructor
+- **XSUAA Configuration** - Renamed `btp_url` to `mcp_url` in YAML configuration
+  - For XSUAA, MCP URL is provided via `mcp_url` in YAML config (not `btp_url`)
+  - MCP URL is optional and not part of authentication
+- **Constants** - Removed constants from exports (internal implementation details)
+  - All file operations are handled by stores through interfaces
+  - Consumers should use `IServiceKeyStore` and `ISessionStore` methods
+- **File Structure** - Organized source code into logical subfolders
+  - `src/auth/` - Authentication logic (browserAuth, clientCredentialsAuth, tokenRefresher, tokenValidator)
+  - `src/cache/` - Token caching
+  - `src/constants/` - Internal constants
+  - `src/loaders/` - Service key loaders (abap, xsuaa)
+  - `src/logger/` - Logging utilities
+  - `src/methods/` - AuthBroker methods (getToken, refreshToken)
+  - `src/parsers/` - Service key parsers
+  - `src/pathResolver/` - Path resolution utilities
+  - `src/providers/` - Token providers (ITokenProvider, XsuaaTokenProvider, BtpTokenProvider)
+  - `src/storage/` - Environment file loaders and token storage (abap, btp, xsuaa)
+  - `src/stores/` - Store implementations (abap, btp, xsuaa)
+  - `src/types/` - Type definitions
+  - `src/utils/` - Utility functions
+- **Test Structure** - Organized tests into subfolders by implementation
+  - `src/__tests__/broker/` - AuthBroker tests
+  - `src/__tests__/stores/abap/`, `src/__tests__/stores/btp/`, `src/__tests__/stores/xsuaa/` - Store tests
+  - `src/__tests__/loaders/abap/`, `src/__tests__/loaders/xsuaa/` - Loader tests
+  - `src/__tests__/storage/abap/`, `src/__tests__/storage/btp/`, `src/__tests__/storage/xsuaa/` - Storage tests
+  - `src/__tests__/parsers/` - Parser tests
+  - `src/__tests__/utils/` - Utility tests
+  - `src/__tests__/helpers/` - Test helpers (configHelpers, testHelpers, AuthBrokerTestHelper)
+- **Renamed XSUAA Components** - Clarified naming for reduced-scope XSUAA authentication
+  - `BtpSessionConfig` → `XsuaaSessionConfig` (for reduced-scope XSUAA)
+  - `BTP_ENV_VARS` → `XSUAA_ENV_VARS` (for reduced-scope XSUAA)
+  - `BTP_HEADERS` → `XSUAA_HEADERS` (for reduced-scope XSUAA)
+  - `BtpSessionStore` → `XsuaaSessionStore` (for reduced-scope XSUAA)
+  - `SafeBtpSessionStore` → `SafeXsuaaSessionStore` (for reduced-scope XSUAA)
+- **XSUAA Session Format** - Uses `XSUAA_*` environment variables instead of `SAP_*`
+  - `XSUAA_MCP_URL` - MCP server URL (optional, not part of authentication)
+  - `XSUAA_JWT_TOKEN` - JWT token for `Authorization: Bearer` header
+  - `XSUAA_REFRESH_TOKEN` - Optional refresh token
+  - `XSUAA_UAA_URL`, `XSUAA_UAA_CLIENT_ID`, `XSUAA_UAA_CLIENT_SECRET` - UAA credentials
+- **MCP URL Handling** - MCP URL is now optional for XSUAA sessions
+  - MCP URL is not part of authentication (only needed for making requests)
+  - Can be provided via YAML config (`mcp_url`), parameter, or request header
+  - Session files can be created without MCP URL (tokens and UAA credentials are sufficient)
+- **Service Key URL Priority** - For XSUAA service keys, `apiurl` is prioritized over `url` for UAA authorization
+- **Store Naming** - Renamed stores for clarity
+  - `FileServiceKeyStore` → `AbapServiceKeyStore` (for ABAP service keys)
+  - `FileSessionStore` → `AbapSessionStore` (for ABAP sessions)
+  - `SafeSessionStore` → `SafeAbapSessionStore` (for in-memory ABAP sessions)
+  - Old names still available as type aliases for backward compatibility
+
+### Removed
+- **ServiceKey Type** - Removed `ServiceKey` type (internal implementation detail)
+- **Internal Types** - Removed internal storage types from exports
+  - `EnvConfig`, `XsuaaSessionConfig`, `BtpSessionConfig` are now internal to store implementations
+- **Constants Export** - Removed constants from public API
+  - `ABAP_AUTHORIZATION_VARS`, `ABAP_CONNECTION_VARS`, etc. are internal
+  - `ABAP_HEADERS`, `XSUAA_HEADERS`, `BTP_HEADERS` are internal
+- **Parser Exports** - Removed parser interfaces and implementations from exports
+  - `IServiceKeyParser`, `AbapServiceKeyParser`, `XsuaaServiceKeyParser` are internal
+
+### Fixed
+- **XSUAA Authentication** - Fixed client_credentials grant type implementation
+  - Uses POST request to UAA token endpoint with `grant_type=client_credentials`
+  - No browser interaction required for XSUAA
+  - Proper error handling for OAuth2 redirect parameters
+- **Test Configuration** - Tests now use YAML configuration file (`tests/test-config.yaml`)
+  - Removed hardcoded paths and destinations
+  - Added `AuthBrokerTestHelper` for creating broker instances from YAML
+  - Tests organized into subfolders by implementation (`abap`, `btp`, `xsuaa`)
+- **Browser Authentication** - Fixed hanging tests when `browser: 'none'` is specified
+  - `startBrowserAuth` now immediately throws error with URL when `browser: 'none'`
+  - Added timeout to `clientCredentialsAuth` to prevent hanging
+- **Session Store Validation** - Fixed validation in `Safe*SessionStore` classes
+  - Now accepts `IConfig` format (with `serviceUrl`/`authorizationToken`) and converts to internal format
+  - Validation messages updated to match actual error messages
+- **YAML Configuration** - Fixed path resolution for test configuration
+  - Uses `findProjectRoot()` to reliably locate `test-config.yaml`
+  - Properly expands `~` to home directory in paths
+  - Added diagnostic logging controlled by `TEST_VERBOSE` environment variable
+
 ## [0.1.5] - 2025-12-02
 
 ### Added

package/README.md

@@ -20,21 +20,29 @@ npm install @mcp-abap-adt/auth-broker
 ## Usage
 
 ```typescript
-import { AuthBroker, FileServiceKeyStore, FileSessionStore, SafeSessionStore } from '@mcp-abap-adt/auth-broker';
+import { 
+  AuthBroker, 
+  AbapServiceKeyStore, 
+  AbapSessionStore, 
+  SafeAbapSessionStore,
+  BtpTokenProvider
+} from '@mcp-abap-adt/auth-broker';
 
 // Use default file-based stores (current working directory)
 const broker = new AuthBroker();
 
 // Use custom file-based stores with specific paths
 const broker = new AuthBroker({
-  serviceKeyStore: new FileServiceKeyStore(['/path/to/destinations']),
-  sessionStore: new FileSessionStore(['/path/to/destinations']),
+  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']),
+  sessionStore: new AbapSessionStore(['/path/to/destinations']),
+  tokenProvider: new BtpTokenProvider(),
 }, 'chrome');
 
 // Use safe in-memory session store (data lost after restart)
 const broker = new AuthBroker({
-  serviceKeyStore: new FileServiceKeyStore(['/path/to/destinations']),
-  sessionStore: new SafeSessionStore(), // In-memory, secure
+  serviceKeyStore: new AbapServiceKeyStore(['/path/to/destinations']),
+  sessionStore: new SafeAbapSessionStore(), // In-memory, secure
+  tokenProvider: new BtpTokenProvider(),
 });
 
 // Get token for destination (loads from .env, validates, refreshes if needed)
@@ -53,7 +61,9 @@ const newToken = await broker.refreshToken('TRIAL');
 
 ### File Structure
 
-#### Environment File (`{destination}.env`)
+#### Environment File for ABAP (`{destination}.env`)
+
+For ABAP connections, use `SAP_*` environment variables:
 
 ```env
 SAP_URL=https://your-system.abap.us10.hana.ondemand.com
@@ -65,7 +75,41 @@ SAP_UAA_CLIENT_ID=client_id
 SAP_UAA_CLIENT_SECRET=client_secret
 ```
 
-#### Service Key File (`{destination}.json`)
+#### Environment File for XSUAA (`{destination}.env`)
+
+For XSUAA connections (reduced scope), use `XSUAA_*` environment variables:
+
+```env
+XSUAA_MCP_URL=https://your-mcp-server.cfapps.eu10.hana.ondemand.com
+XSUAA_JWT_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+XSUAA_REFRESH_TOKEN=refresh_token_string
+XSUAA_UAA_URL=https://your-account.authentication.eu10.hana.ondemand.com
+XSUAA_UAA_CLIENT_ID=client_id
+XSUAA_UAA_CLIENT_SECRET=client_secret
+```
+
+**Note**: `XSUAA_MCP_URL` is optional - it's not part of authentication, only needed for making requests. The token and UAA credentials are sufficient for authentication.
+
+#### Environment File for BTP (`{destination}.env`)
+
+For BTP connections (full scope for ABAP systems), use `BTP_*` environment variables:
+
+```env
+BTP_ABAP_URL=https://your-system.abap.us10.hana.ondemand.com
+BTP_JWT_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+BTP_REFRESH_TOKEN=refresh_token_string
+BTP_UAA_URL=https://your-account.authentication.eu10.hana.ondemand.com
+BTP_UAA_CLIENT_ID=client_id
+BTP_UAA_CLIENT_SECRET=client_secret
+BTP_SAP_CLIENT=100
+BTP_LANGUAGE=EN
+```
+
+**Note**: `BTP_ABAP_URL` is required - it's the ABAP system URL. All parameters (except tokens) come from service key.
+
+#### Service Key File for ABAP (`{destination}.json`)
+
+Standard ABAP service key format:
 
 ```json
 {
@@ -78,6 +122,41 @@ SAP_UAA_CLIENT_SECRET=client_secret
 }
 ```
 
+#### Service Key File for XSUAA (`{destination}.json`)
+
+Direct XSUAA service key format (from BTP):
+
+```json
+{
+  "url": "https://your-account.authentication.eu10.hana.ondemand.com",
+  "apiurl": "https://api.authentication.eu10.hana.ondemand.com",
+  "clientid": "your_client_id",
+  "clientsecret": "your_client_secret"
+}
+```
+
+**Note**: For XSUAA service keys, `apiurl` is prioritized over `url` for UAA authorization if present.
+
+## XSUAA vs BTP Authentication
+
+This package supports two types of BTP authentication:
+
+### XSUAA (Reduced Scope)
+- **Purpose**: Access BTP services with limited scopes
+- **Service Key**: Contains only UAA credentials (no ABAP URL)
+- **Session Store**: `XsuaaSessionStore` (uses `XSUAA_*` environment variables)
+- **Authentication**: Client credentials grant type (no browser required)
+- **MCP URL**: Optional, provided separately (from YAML config `mcp_url`, parameter, or request header)
+- **Use Case**: Accessing BTP services like MCP servers with reduced permissions
+
+### BTP (Full Scope for ABAP)
+- **Purpose**: Access ABAP systems with full roles and scopes
+- **Service Key**: Contains UAA credentials and ABAP URL
+- **Session Store**: `BtpSessionStore` (uses `BTP_*` environment variables)
+- **Authentication**: Browser-based OAuth2 (like ABAP) or refresh token
+- **ABAP URL**: Required, from service key or YAML configuration
+- **Use Case**: Accessing ABAP systems in BTP with full permissions
+
 ## API
 
 ### `AuthBroker`
@@ -85,24 +164,42 @@ SAP_UAA_CLIENT_SECRET=client_secret
 #### Constructor
 
 ```typescript
-new AuthBroker(stores?: { serviceKeyStore?: IServiceKeyStore; sessionStore?: ISessionStore }, browser?: string, logger?: Logger)
+new AuthBroker(
+  stores?: { 
+    serviceKeyStore?: IServiceKeyStore; 
+    sessionStore?: ISessionStore;
+    tokenProvider?: ITokenProvider;
+  }, 
+  browser?: string, 
+  logger?: Logger
+)
 ```
 
 - `stores` - Optional object with custom storage implementations:
-  - `serviceKeyStore` - Store for service keys (default: `FileServiceKeyStore()`)
-  - `sessionStore` - Store for session data (default: `FileSessionStore()`)
+  - `serviceKeyStore` - Store for service keys (default: `AbapServiceKeyStore()`)
+  - `sessionStore` - Store for session data (default: `AbapSessionStore()`)
+  - `tokenProvider` - Token provider for token acquisition (default: `BtpTokenProvider()`)
   - Available implementations:
-    - `FileServiceKeyStore(searchPaths?)` - File-based service key store
-    - `FileSessionStore(searchPaths?)` - File-based session store (persists to disk)
-    - `SafeSessionStore()` - In-memory session store (secure, data lost after restart)
+    - **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()`
 - `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
 
 #### Methods
 
 ##### `getToken(destination: string): Promise<string>`
 
-Gets authentication token for destination. Tries to load from `.env` file, validates it, and refreshes if needed.
+Gets authentication token for destination. Tries to load from session store, validates it, and refreshes if needed using a fallback chain:
+
+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
+
+**Note**: 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>`
 
@@ -116,6 +213,70 @@ Clear cached token for specific destination.
 
 Clear all cached tokens.
 
+### Token Providers
+
+The package uses `ITokenProvider` interface for token acquisition. Two implementations are available:
+
+- **`XsuaaTokenProvider`** - For XSUAA authentication (reduced scope)
+  - Uses client_credentials grant type
+  - No browser interaction required
+  - No refresh token provided
+
+- **`BtpTokenProvider`** - For BTP/ABAP authentication (full scope)
+  - Uses browser-based OAuth2 flow (if no refresh token)
+  - Uses refresh token if available
+  - Provides refresh token for future use
+
+**Example Usage:**
+
+```typescript
+import {
+  AuthBroker,
+  XsuaaServiceKeyStore,
+  XsuaaSessionStore,
+  XsuaaTokenProvider,
+  BtpTokenProvider
+} from '@mcp-abap-adt/auth-broker';
+
+// XSUAA authentication (no browser needed)
+const xsuaaBroker = new AuthBroker({
+  serviceKeyStore: new XsuaaServiceKeyStore(['/path/to/keys']),
+  sessionStore: new XsuaaSessionStore(['/path/to/sessions']),
+  tokenProvider: new XsuaaTokenProvider(),
+}, 'none');
+
+// BTP authentication (browser or refresh token)
+const btpBroker = new AuthBroker({
+  serviceKeyStore: new AbapServiceKeyStore(['/path/to/keys']),
+  sessionStore: new BtpSessionStore(['/path/to/sessions']),
+  tokenProvider: new BtpTokenProvider(),
+});
+```
+
+### Utility Script
+
+Generate `.env` files from service keys:
+
+```bash
+npm run generate-env <destination> [service-key-path] [session-path]
+```
+
+**Examples:**
+```bash
+# Generate .env from service key (auto-detect paths)
+npm run generate-env mcp
+
+# Specify paths explicitly
+npm run generate-env mcp ./mcp.json ./mcp.env
+
+# Use absolute paths
+npm run generate-env TRIAL ~/.config/mcp-abap-adt/service-keys/TRIAL.json ~/.config/mcp-abap-adt/sessions/TRIAL.env
+```
+
+The script automatically detects service key type (ABAP or XSUAA) and uses the appropriate authentication flow:
+- **ABAP**: Opens browser for OAuth2 authorization code flow
+- **XSUAA**: Uses client_credentials grant type (no browser required)
+
 ## Testing
 
 Tests are located in `src/__tests__/` and use Jest as the test runner.
@@ -160,9 +321,13 @@ Tests are designed to run sequentially (guaranteed by `maxWorkers: 1` and `maxCo
 
 ### Test Setup
 
-Place your service key file in `./test-destinations/TRIAL.json` to run tests 2 and 3.
+1. Copy `tests/test-config.yaml.template` to `tests/test-config.yaml`
+2. Fill in configuration values (paths, destinations, MCP URL for XSUAA)
+3. Place service key files in configured `service_keys_dir`:
+   - `{destination}.json` for ABAP tests (e.g., `trial.json`)
+   - `{btp_destination}.json` for XSUAA tests (e.g., `btp.json`)
 
-Tests will automatically skip if required files are missing or present when they shouldn't be.
+Tests will automatically skip if required files are missing or configuration contains placeholders.
 
 ## Documentation
 

package/bin/generate-env-from-service-key.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env tsx
+/**
+ * Generate .env file from service key
+ * 
+ * Usage:
+ *   npm run generate-env <destination> [service-key-path] [session-path]
+ *   or
+ *   npx tsx bin/generate-env-from-service-key.ts <destination> [service-key-path] [session-path]
+ * 
+ * Examples:
+ *   npm run generate-env mcp
+ *   npm run generate-env mcp ./mcp.json ./mcp.env
+ *   npm run generate-env TRIAL ~/.config/mcp-abap-adt/service-keys/TRIAL.json
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { AuthBroker } from '../src/AuthBroker';
+import { AbapServiceKeyStore, AbapSessionStore } from '@mcp-abap-adt/auth-stores-btp';
+import { XsuaaServiceKeyStore, XsuaaSessionStore } from '@mcp-abap-adt/auth-stores-xsuaa';
+import { BtpTokenProvider, XsuaaTokenProvider } from '@mcp-abap-adt/auth-providers';
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length === 0) {
+    console.error('Usage: generate-env-from-service-key <destination> [service-key-path] [session-path]');
+    console.error('');
+    console.error('Examples:');
+    console.error('  generate-env-from-service-key mcp');
+    console.error('  generate-env-from-service-key mcp ./mcp.json ./mcp.env');
+    console.error('  generate-env-from-service-key TRIAL ~/.config/mcp-abap-adt/service-keys/TRIAL.json');
+    process.exit(1);
+  }
+
+  const destination = args[0];
+  const serviceKeyPath = args[1] || path.join(process.cwd(), `${destination}.json`);
+  const sessionPath = args[2] || path.join(process.cwd(), `${destination}.env`);
+
+  // Resolve paths
+  const resolvedServiceKeyPath = path.resolve(serviceKeyPath);
+  const resolvedSessionPath = path.resolve(sessionPath);
+  const serviceKeyDir = path.dirname(resolvedServiceKeyPath);
+  const sessionDir = path.dirname(resolvedSessionPath);
+
+  // Check if service key file exists
+  if (!fs.existsSync(resolvedServiceKeyPath)) {
+    console.error(`❌ Service key file not found: ${resolvedServiceKeyPath}`);
+    process.exit(1);
+  }
+
+  console.log(`📁 Service key: ${resolvedServiceKeyPath}`);
+  console.log(`📁 Session file: ${resolvedSessionPath}`);
+
+  try {
+    // Load service key to determine type
+    const rawServiceKey = JSON.parse(fs.readFileSync(resolvedServiceKeyPath, 'utf8'));
+    const isXsuaa = rawServiceKey.url && rawServiceKey.url.includes('authentication') && !rawServiceKey.uaa;
+
+    // Create appropriate stores
+    const serviceKeyStore = isXsuaa
+      ? new XsuaaServiceKeyStore([serviceKeyDir])
+      : new AbapServiceKeyStore([serviceKeyDir]);
+    
+    const sessionStore = isXsuaa
+      ? new XsuaaSessionStore([sessionDir])
+      : new AbapSessionStore([sessionDir]);
+
+    // Create token provider
+    const tokenProvider = isXsuaa
+      ? new XsuaaTokenProvider()
+      : new BtpTokenProvider();
+
+    // Create AuthBroker
+    // For ABAP, use 'system' browser (will open browser for auth)
+    // For XSUAA, browser doesn't matter (uses client_credentials)
+    const broker = new AuthBroker({
+      serviceKeyStore,
+      sessionStore,
+      tokenProvider,
+    }, isXsuaa ? 'none' : 'system');
+
+    console.log(`🔐 Getting token for destination "${destination}"...`);
+    if (isXsuaa) {
+      console.log(`   Using client_credentials grant type (no browser required)`);
+    } else {
+      console.log(`   Using browser authentication (browser will open)`);
+    }
+    
+    // Get token (will use client_credentials for XSUAA or browser auth for ABAP)
+    const token = await broker.getToken(destination);
+    
+    console.log(`✅ Token obtained successfully`);
+
+    // Check if session file was created
+    if (fs.existsSync(resolvedSessionPath)) {
+      console.log(`✅ Session file created: ${resolvedSessionPath}`);
+      
+      // Show service URL if available
+      const connConfig = await broker.getConnectionConfig(destination);
+      if (connConfig?.serviceUrl) {
+        if (isXsuaa) {
+          console.log(`📁 MCP URL: ${connConfig.serviceUrl}`);
+        } else {
+          console.log(`📁 SAP URL: ${connConfig.serviceUrl}`);
+        }
+      } else if (isXsuaa) {
+        console.log(`💡 Note: MCP URL not set in session (optional for XSUAA).`);
+        console.log(`   Provide MCP URL via YAML config, parameter, or request header when making requests.`);
+      }
+    } else {
+      console.log(`⚠️  Session file was not created. Token is cached in memory.`);
+    }
+
+  } catch (error: any) {
+    console.error(`❌ Error: ${error.message}`);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+