# Auth Broker Roadmap
**Status:** ✅ Completed
**Priority:** High
**Created:** 2025-01-27
**Last Updated:** 2025-11-30
**Note:** This roadmap has been completed. The `@mcp-abap-adt/auth-broker` package is now published and integrated into `mcp-abap-adt` server. See [Client Configuration Guide](../../user-guide/CLIENT_CONFIGURATION.md#destination-based-authentication) for usage details.
## Goal
Create a new package `@mcp-abap-adt/auth-broker` that handles JWT authentication based on HTTP headers (`x-sap-auth-type: jwt` and `x-mcp-destination`). The package will manage token retrieval, validation, and automatic refresh using service keys when needed.
## Requirements
### Core Functionality
1. **Header-based Authentication Detection**
- Detect `x-sap-auth-type: jwt` header
- Extract destination name from `x-mcp-destination` header (e.g., "TRIAL")
- Only process when both headers are present
2. **Environment File Lookup**
- Search for `{destination}.env` file (e.g., `TRIAL.env`) in a configurable directory
- Extract JWT token from the `.env` file
- Use token for authentication if file is found
3. **Token Validation**
- Test connection using the token from `.env` file
- Detect expired tokens (401/403 errors that indicate auth failure, not permission issues)
4. **Service Key Fallback**
- If `.env` file is not found OR token is expired:
- Search for `{destination}.json` file (e.g., `TRIAL.json`) containing service key
- Use `@mcp-abap-adt/connection` utilities to refresh/obtain new token
- Save new token to `.env` file for future use
5. **Token Management**
- Cache tokens per destination
- Provide `getToken(destination)` method
- Provide `refreshToken(destination)` method
- Handle token storage and retrieval
## Architecture
### Package Structure
```
mcp-abap-adt-auth-broker/
├── src/
│ ├── AuthBroker.ts # Main class with getToken/refreshToken methods
│ ├── envLoader.ts # Load .env files by destination name
│ ├── serviceKeyLoader.ts # Load service key JSON files
│ ├── tokenValidator.ts # Validate token by testing connection
│ ├── tokenRefresher.ts # Refresh token using service key
│ └── index.ts # Package exports
├── package.json
├── tsconfig.json
└── README.md
```
### Dependencies
- `@mcp-abap-adt/connection` - For token refresh utilities (`refreshJwtToken`)
- `axios` - For connection testing
- `dotenv` - For parsing `.env` files
- `fs` / `path` - For file system operations
## Implementation Steps
### Phase 1: Repository Setup
1. **Create new repository**
- [ ] Create directory `/home/okyslytsia/prj/mcp-abap-adt-auth-broker`
- [ ] Initialize npm package with name `@mcp-abap-adt/auth-broker`
- [ ] Set up TypeScript configuration
- [ ] Create basic package structure
2. **Package Configuration**
- [ ] Configure `package.json` with proper name, version, and dependencies
- [ ] Set up TypeScript build configuration
- [ ] Configure exports in `package.json` (main, types, files)
- [ ] Add build scripts
### Phase 2: Core Components
3. **Environment File Loader**
- [ ] Create `envLoader.ts` module
- [ ] Implement `loadEnvFile(destination: string, basePath?: string): Promise<EnvConfig | null>`
- [ ] Search for `{destination}.env` in configurable directory
- [ ] Parse `.env` file and extract:
- `SAP_JWT_TOKEN`
- `SAP_REFRESH_TOKEN` (optional)
- `SAP_URL`
- `SAP_CLIENT` (optional)
- `SAP_UAA_URL` (optional, for refresh)
- `SAP_UAA_CLIENT_ID` (optional, for refresh)
- `SAP_UAA_CLIENT_SECRET` (optional, for refresh)
- [ ] Return structured config object or null if not found
4. **Service Key Loader**
- [ ] Create `serviceKeyLoader.ts` module
- [ ] Implement `loadServiceKey(destination: string, basePath?: string): Promise<ServiceKey | null>`
- [ ] Search for `{destination}.json` file
- [ ] Parse JSON and validate structure (must have `uaa` object with `url`, `clientid`, `clientsecret`)
- [ ] Extract ABAP URL from service key (`url`, `abap.url`, or `sap_url`)
- [ ] Return structured service key object or null if not found
5. **Token Validator**
- [ ] Create `tokenValidator.ts` module
- [ ] Implement `validateToken(token: string, sapUrl: string): Promise<boolean>`
- [ ] Make test request to SAP system (e.g., `/sap/bc/adt/core/discovery`)
- [ ] Handle 401/403 errors:
- Distinguish between auth errors (token expired) and permission errors
- Return `false` for expired tokens
- Return `true` for valid tokens
- [ ] Handle network errors appropriately
6. **Token Refresher**
- [ ] Create `tokenRefresher.ts` module
- [ ] Import `refreshJwtToken` from `@mcp-abap-adt/connection`
- [ ] Implement `refreshTokenFromServiceKey(serviceKey: ServiceKey): Promise<TokenRefreshResult>`
- [ ] Use service key to obtain initial token (if needed) or refresh existing token
- [ ] Handle OAuth flow if refresh token is not available (may need to use browser flow or client credentials)
- [ ] Return new access token and refresh token
### Phase 3: Main AuthBroker Class
7. **AuthBroker Class Implementation**
- [ ] Create `AuthBroker.ts` class
- [ ] Constructor accepts:
- `basePath?: string` - Base directory for searching `.env` and `.json` files (default: current working directory or configurable)
- [ ] Implement `getToken(destination: string): Promise<string>`
- Check cache for existing valid token
- Load `{destination}.env` file
- Extract token from `.env`
- Validate token by testing connection
- If valid, cache and return token
- If invalid or not found, call `refreshToken()`
- [ ] Implement `refreshToken(destination: string): Promise<string>`
- Load `{destination}.json` service key file
- Use token refresher to obtain new token
- Save new token to `{destination}.env` file
- Cache new token
- Return new token
- [ ] Implement token caching (in-memory cache per destination)
- [ ] Implement error handling and logging
8. **Token Storage**
- [ ] Implement `saveTokenToEnv(destination: string, token: string, refreshToken?: string, config?: Partial<EnvConfig>): Promise<void>`
- [ ] Update or create `{destination}.env` file
- [ ] Preserve existing values that are not being updated
- [ ] Write file atomically (write to temp file, then rename)
### Phase 4: NPM Publishing Setup
9. **Package.json Configuration**
- [ ] Configure `package.json` for npm publishing:
- [ ] Set `"name": "@mcp-abap-adt/auth-broker"`
- [ ] Set initial version (e.g., `"0.1.0"`)
- [ ] Add `"publishConfig": { "access": "public" }` for scoped package
- [ ] Configure `"files"` array to include only necessary files:
- `dist/` - compiled JavaScript and TypeScript definitions
- `README.md` - package documentation
- `LICENSE` - license file
- [ ] Set `"main": "dist/index.js"` and `"types": "dist/index.d.ts"`
- [ ] Add proper `"repository"` field with GitHub URL
- [ ] Add `"keywords"` for npm searchability
- [ ] Add `"homepage"` and `"bugs"` URLs
- [ ] Configure `"engines"` (Node.js >= 18.0.0)
- [ ] Add `"prepublishOnly"` script to build before publishing
10. **NPM Account Setup**
- [ ] Verify npm account access to `@mcp-abap-adt` scope
- [ ] If needed, create organization or request access to existing scope
- [ ] Configure npm authentication:
- [ ] Run `npm login` or configure `.npmrc` with auth token
- [ ] Verify access: `npm whoami`
- [ ] Test scope access: `npm access ls-packages @mcp-abap-adt`
11. **NPM Configuration Files**
- [ ] Create `.npmrc` file (if needed) with:
- [ ] `package-lock=true` - ensure lock file is generated
- [ ] Other npm settings as needed (see existing packages for reference)
- [ ] Add `.npmignore` file (if needed) to exclude:
- [ ] `src/` - source files (only `dist/` should be published)
- [ ] `node_modules/`
- [ ] `*.test.ts`, `*.spec.ts` - test files
- [ ] `tsconfig.json`, `jest.config.js` - build configs
- [ ] `.git/`, `.github/` - version control files
- [ ] Development files
12. **Build and Test Package Locally**
- [ ] Run `npm run build` to ensure TypeScript compiles correctly
- [ ] Run `npm pack` to create `.tgz` package locally
- [ ] Verify package contents: `tar -tzf *.tgz | head -20`
- [ ] Test package installation locally:
```bash
npm pack
npm install -g ./mcp-abap-adt-auth-broker-*.tgz
```
- [ ] Verify package can be imported in test project
- [ ] Clean up test installation
13. **GitHub Repository Setup** (if separate repo)
- [ ] Create GitHub repository (if package is in separate repo)
- [ ] Initialize git repository
- [ ] Add `.gitignore` file
- [ ] Create initial commit
- [ ] Push to GitHub
- [ ] Update `package.json` repository field with correct URL
14. **GitHub Actions for Publishing** (optional but recommended)
- [ ] Create `.github/workflows/publish-npm.yml`:
- [ ] Trigger on version tags (`v*.*.*`)
- [ ] Setup Node.js
- [ ] Install dependencies
- [ ] Run tests
- [ ] Build package
- [ ] Publish to npm using `NPM_TOKEN` secret
- [ ] Add `NPM_TOKEN` to GitHub repository secrets
- [ ] Test workflow with dry-run or test publish
15. **First Publication**
- [ ] Ensure all code is complete and tested
- [ ] Update version in `package.json` (e.g., `0.1.0`)
- [ ] Build package: `npm run build`
- [ ] Verify package: `npm pack`
- [ ] Publish to npm:
```bash
npm publish --access public
```
- [ ] Verify publication:
- [ ] Check npm registry: `npm view @mcp-abap-adt/auth-broker`
- [ ] Test installation: `npm install @mcp-abap-adt/auth-broker`
- [ ] Verify package works in test project
16. **Version Management**
- [ ] Document versioning strategy (semantic versioning)
- [ ] Set up `CHANGELOG.md` for tracking changes
- [ ] Document release process
- [ ] Consider using `npm version` command for version bumps
### Phase 5: Integration with mcp-abap-adt
17. **Package Installation**
- [ ] Add `@mcp-abap-adt/auth-broker` as dependency to `mcp-abap-adt/package.json`
- [ ] Install package: `npm install @mcp-abap-adt/auth-broker`
- [ ] Verify package is installed correctly
18. **Header Processing Integration**
- [ ] Modify `applyAuthHeaders()` method in `mcp_abap_adt_server` class
- [ ] Add detection for `x-mcp-destination` header
- [ ] When `x-sap-auth-type: jwt` AND `x-mcp-destination` are present:
- Create `AuthBroker` instance
- Call `getToken(destination)` to obtain token
- Use returned token instead of token from `x-sap-jwt-token` header
- Update `processJwtConfigUpdate()` to use broker token
19. **Configuration**
- [ ] Add configuration option for base path where `.env` and `.json` files are stored
- [ ] Default to current working directory or a configurable directory (e.g., `~/.mcp-abap-adt/destinations/`)
- [ ] Allow override via environment variable (e.g., `MCP_AUTH_BROKER_BASE_PATH`)
### Phase 6: Testing and Documentation
20. **Unit Tests**
- [ ] Test `envLoader` with various `.env` file formats
- [ ] Test `serviceKeyLoader` with valid and invalid service keys
- [ ] Test `tokenValidator` with valid, expired, and invalid tokens
- [ ] Test `tokenRefresher` with service keys
- [ ] Test `AuthBroker.getToken()` flow
- [ ] Test `AuthBroker.refreshToken()` flow
- [ ] Test error handling scenarios
21. **Integration Tests**
- [ ] Test full flow: header → destination → `.env` file → token validation → token refresh if needed
- [ ] Test with real SAP system (if available)
- [ ] Test token caching behavior
- [ ] Test concurrent requests for same destination
22. **Documentation**
- [ ] Write README.md for `auth-broker` package
- [ ] Document API (AuthBroker class methods)
- [ ] Document file structure requirements (`.env` and `.json` file formats)
- [ ] Document configuration options
- [ ] Add usage examples
- [ ] Update `mcp-abap-adt` documentation to explain new header-based destination authentication
## File Structure Details
### Environment File Format (`{destination}.env`)
```env
SAP_URL=https://your-system.abap.us10.hana.ondemand.com
SAP_CLIENT=100
SAP_JWT_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
SAP_REFRESH_TOKEN=refresh_token_string
SAP_UAA_URL=https://your-account.authentication.us10.hana.ondemand.com
SAP_UAA_CLIENT_ID=client_id
SAP_UAA_CLIENT_SECRET=client_secret
```
### Service Key File Format (`{destination}.json`)
```json
{
"url": "https://your-system.abap.us10.hana.ondemand.com",
"uaa": {
"url": "https://your-account.authentication.us10.hana.ondemand.com",
"clientid": "your_client_id",
"clientsecret": "your_client_secret"
}
}
```
## API Design
### AuthBroker Class
```typescript
export class AuthBroker {
constructor(basePath?: string);
/**
* Get authentication token for destination.
* Tries to load from .env file, validates it, and refreshes if needed.
*/
getToken(destination: string): Promise<string>;
/**
* Force refresh token for destination using service key.
*/
refreshToken(destination: string): Promise<string>;
/**
* Clear cached token for destination.
*/
clearCache(destination: string): void;
/**
* Clear all cached tokens.
*/
clearAllCache(): void;
}
```
## Integration Points
### In mcp-abap-adt/src/index.ts
Modify `applyAuthHeaders()` method:
```typescript
// When x-sap-auth-type: jwt AND x-mcp-destination are present
if (isJwtAuth && destination) {
const authBroker = new AuthBroker(configurableBasePath);
const token = await authBroker.getToken(destination);
// Use token instead of header token
this.processJwtConfigUpdate(sapUrl, token, refreshToken, sessionId);
}
```
## Configuration
### Environment Variables
- `MCP_AUTH_BROKER_BASE_PATH` - Base directory for searching `.env` and `.json` files (default: current working directory)
### Default File Locations
1. Check `MCP_AUTH_BROKER_BASE_PATH` if set
2. Fallback to current working directory
3. Future: Support `~/.mcp-abap-adt/destinations/` as default
## Error Handling
- File not found: Log warning, attempt service key refresh
- Invalid token: Attempt refresh using service key
- Service key not found: Throw error with clear message
- Token refresh failure: Throw error with details
- Network errors: Retry with exponential backoff (if applicable)
## Future Enhancements
- Support for multiple base paths (search in multiple directories)
- Token expiration prediction (refresh before expiration)
- Support for encrypted service key files
- Integration with keychain/credential stores
- Support for destination-specific configuration files
- Metrics and monitoring hooks
## Dependencies
### Required
- `@mcp-abap-adt/connection` - For `refreshJwtToken` utility
- `axios` - For HTTP requests (token validation)
- `dotenv` - For parsing `.env` files
### Optional
- `fs-extra` - For better file operations (if needed)
- `winston` or similar - For structured logging (if needed)
## Notes
- The package should be lightweight and focused only on token management
- It should not handle actual ADT requests - that's the responsibility of `@mcp-abap-adt/connection`
- Token validation should be minimal (just test connection, don't do full ADT operations)
- The package should be stateless where possible, but token caching is acceptable for performance
- Consider thread-safety if multiple requests come in for the same destination simultaneously
