Header validator for MCP ABAP ADT - validates and prioritizes authentication headers
npm install @mcp-abap-adt/header-validatorHeader validator for MCP ABAP ADT - validates and prioritizes authentication headers.
- ✅ Header Validation: Validates authentication headers for MCP ABAP ADT servers
- ✅ Priority System: Automatically prioritizes authentication methods
- ✅ Error Reporting: Detailed error messages and warnings
- ✅ Type Safety: Full TypeScript support with type definitions
Interface-Only Communication: This package follows a fundamental development principle: all interactions with external dependencies happen ONLY through interfaces. The code knows NOTHING beyond what is defined in the interfaces.
This means:
- Does not know about concrete implementation classes from other packages
- Does not know about internal data structures or methods not defined in interfaces
- Does not make assumptions about implementation behavior beyond interface contracts
- Does not access properties or methods not explicitly defined in interfaces
This principle ensures:
- Loose coupling: Validator is decoupled from concrete implementations in other packages
- Flexibility: New implementations can be added without modifying validator
- Testability: Easy to mock dependencies for testing
- Maintainability: Changes to implementations don't affect validator
This package is responsible for:
1. Header validation: Validates authentication headers from HTTP requests
2. Priority resolution: Determines which authentication method to use based on header presence and priority rules
3. Configuration extraction: Extracts authentication configuration from headers
4. Error reporting: Provides detailed validation errors and warnings
#### What This Package Does
- Validates headers: Checks authentication headers for validity and completeness
- Prioritizes methods: Determines authentication method priority (SAP destination > MCP destination > JWT token > Basic auth)
- Extracts config: Extracts SapConfig from validated headers
- Reports errors: Provides detailed error messages and warnings for invalid configurations
- Type safety: Returns typed validation results with configuration objects
#### What This Package Does NOT Do
- Does NOT handle authentication: Authentication is handled by @mcp-abap-adt/connection and @mcp-abap-adt/auth-broker
- Does NOT manage tokens: Token management is handled by @mcp-abap-adt/auth-broker
- Does NOT make HTTP requests: HTTP requests are handled by @mcp-abap-adt/connection
- Does NOT store configuration: Configuration storage is handled by consumers
- Does NOT know about destinations: Destination resolution is handled by @mcp-abap-adt/auth-broker
This package interacts with external packages ONLY through interfaces:
- @mcp-abap-adt/connection: Uses SapConfig type for configuration - does not know about concrete connection implementation
- No direct dependencies on other packages: All interactions happen through well-defined types and interfaces
``bash`
npm install @mcp-abap-adt/header-validator
`typescript
import { validateAuthHeaders } from '@mcp-abap-adt/header-validator';
import { IncomingHttpHeaders } from 'http';
const headers: IncomingHttpHeaders = {
'x-sap-url': 'https://test.sap.com',
'x-mcp-destination': 'TRIAL',
// Note: x-sap-auth-type not needed - always uses JWT
};
const result = validateAuthHeaders(headers);
if (result.isValid && result.config) {
console.log('Auth method:', result.config.priority);
console.log('Destination:', result.config.destination);
} else {
console.error('Validation errors:', result.errors);
}
`
The validator supports four authentication methods, ordered by priority (highest to lowest):
Priority: AuthMethodPriority.SAP_DESTINATION (4)
Required Headers:
- x-sap-url - SAP system URLx-sap-destination
- - Destination name (e.g., "S4HANA_E19")
Optional Headers:
- x-sap-client - SAP client numberx-sap-login
- / x-sap-password - Username/password (edge cases)
Description: Simplest configuration - uses AuthBroker to manage tokens. Always uses JWT authentication. No x-sap-auth-type header needed.
Example:
`typescript`
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': 'S4HANA_E19',
};
Notes:
- Does NOT require x-sap-auth-type (always JWT)x-sap-auth-type
- If is provided, it will be ignored (warning issued)x-sap-jwt-token
- If is also provided, it will be ignored (warning issued)
- Requires AuthBroker to be initialized in the server
- Automatically handles token refresh and validation
Priority: AuthMethodPriority.MCP_DESTINATION (3)
Required Headers:
- x-sap-url - SAP system URLx-mcp-destination
- - Destination name (e.g., "TRIAL", "PRODUCTION")
Optional Headers:
- x-sap-client - SAP client number
Description: Uses AuthBroker to manage tokens based on destination. Tokens are loaded from {destination}.env files, validated, and automatically refreshed when needed. Always uses JWT authentication.
Example:
`typescript`
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-mcp-destination': 'TRIAL',
// Note: x-sap-auth-type not needed - always uses JWT
};
Notes:
- Does NOT require x-sap-auth-type (always JWT)x-sap-auth-type
- If is provided, it will be ignored (warning issued)x-sap-jwt-token
- If is also provided, it will be ignored (warning issued)
- Requires AuthBroker to be initialized in the server
- Automatically handles token refresh and validation
Priority: AuthMethodPriority.DIRECT_JWT (2)
Required Headers:
- x-sap-url - SAP system URLx-sap-auth-type
- - Must be jwt or xsuaax-sap-jwt-token
- - JWT access token
Optional Headers:
- x-sap-refresh-token - Refresh token for automatic token renewalx-sap-uaa-url
- / uaa-url - UAA URLx-sap-uaa-client-id
- / uaa-client-id - UAA Client IDx-sap-uaa-client-secret
- / uaa-client-secret - UAA Client Secretx-sap-client
- - SAP client number
Description: Direct JWT token authentication. Token is provided directly in headers.
Example:
`typescript`
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'jwt',
'x-sap-jwt-token': 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
'x-sap-refresh-token': 'refresh_token_here', // optional
};
Notes:
- Token must be at least 10 characters long
- Refresh token is optional but recommended for automatic token renewal
Priority: AuthMethodPriority.BASIC (1)
Required Headers:
- x-sap-url - SAP system URLx-sap-auth-type
- - Must be basicx-sap-login
- - Usernamex-sap-password
- - Password
Description: Basic HTTP authentication with username and password.
Example:
`typescript`
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'basic',
'x-sap-login': 'username',
'x-sap-password': 'password',
};
Notes:
- Used primarily for on-premise SAP systems
- Credentials are sent in plain text (use HTTPS in production)
#### 1. SAP Destination Only (Simplest - Recommended)
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': 'S4HANA_E19',
}
// No x-sap-auth-type needed - always JWT
#### 2. MCP Destination Only
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-mcp-destination': 'TRIAL',
// Note: x-sap-auth-type not needed - always uses JWT
}
#### 3. Direct JWT Only
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'jwt',
'x-sap-jwt-token': 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
'x-sap-refresh-token': 'refresh_token', // optional
}
#### 4. Basic Auth Only
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'basic',
'x-sap-login': 'username',
'x-sap-password': 'password',
}
#### 5. SAP Destination + Auth Type (Warning Issued)
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': 'S4HANA_E19',
'x-sap-auth-type': 'jwt', // ignored (warning)
}
Result: SAP Destination auth is used, auth-type is ignored (warning issued)
#### 6. Destination + Direct JWT (Warning Issued)
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': 'S4HANA_E19',
'x-sap-jwt-token': 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', // ignored
}
Result: SAP Destination auth is used (Priority 4), direct JWT token is ignored (warning issued)
#### 7. Multiple Destinations (SAP Takes Priority)
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': 'S4HANA_E19', // Priority 4
'x-mcp-destination': 'TRIAL', // Priority 3 - ignored
}
Result: SAP Destination auth is used, MCP destination is ignored
#### 1. Missing Required Headers
`typescript`
{
'x-sap-url': 'https://test.sap.com',
// Missing x-sap-auth-type
}x-sap-auth-type header is required
Error:
#### 2. Invalid Auth Type
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'invalid',
}x-sap-auth-type must be one of: jwt, xsuaa, basic
Error:
#### 3. JWT Auth Without Token or Destination
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'jwt',
// Missing x-sap-destination, x-mcp-destination, and x-sap-jwt-token
}JWT authentication requires either x-sap-destination, x-mcp-destination, or x-sap-jwt-token header
Error:
#### 4. Basic Auth Without Credentials
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'basic',
// Missing x-sap-login and/or x-sap-password
}Basic authentication requires x-sap-login and x-sap-password headers
Error:
#### 5. Empty Values
`typescript`
{
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': ' ', // empty after trim
}x-sap-destination header is empty
Error:
#### 6. Invalid URL
`typescript`
{
'x-sap-url': 'not-a-valid-url',
'x-sap-auth-type': 'jwt',
'x-sap-jwt-token': 'token',
}x-sap-url is not a valid URL
Error:
When multiple authentication methods are detected, the validator automatically selects the highest priority method:
1. SAP Destination (Priority 4) - Always selected if x-sap-destination is presentx-mcp-destination
2. MCP Destination (Priority 3) - Selected if is present (always uses JWT, no x-sap-auth-type needed)x-sap-auth-type: jwt
3. Direct JWT (Priority 2) - Selected if JWT token is provided (requires )x-sap-auth-type: basic
4. Basic (Priority 1) - Selected only if basic auth headers are present (requires )
`typescript
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': 'S4HANA_E19', // Priority 4 (selected)
'x-sap-auth-type': 'jwt', // Ignored (warning)
'x-mcp-destination': 'TRIAL', // Priority 3 (ignored)
'x-sap-jwt-token': 'token', // Priority 2 (ignored)
'x-sap-login': 'user', // Priority 1 (ignored)
'x-sap-password': 'pass', // Priority 1 (ignored)
};
const result = validateAuthHeaders(headers);
// result.config.priority === AuthMethodPriority.SAP_DESTINATION (4)
// result.warnings includes: "x-sap-auth-type is ignored when x-sap-destination is present"
// result.warnings includes: "x-sap-jwt-token is ignored when x-sap-destination is present"
`
Validates and prioritizes authentication headers.
Parameters:
- headers - HTTP headers object (optional)
Returns: HeaderValidationResult object with:isValid: boolean
- - Whether the configuration is validconfig?: ValidatedAuthConfig
- - Validated authentication configuration (if valid)errors: string[]
- - List of validation errorswarnings: string[]
- - List of warnings (e.g., ignored headers)
`typescript`
interface ValidatedAuthConfig {
priority: AuthMethodPriority; // Authentication method priority
authType: AuthType; // 'jwt' | 'xsuaa' | 'basic'
sapUrl: string; // SAP system URL
destination?: string; // Destination name (for destination-based auth)
jwtToken?: string; // JWT token (for direct JWT auth)
refreshToken?: string; // Refresh token (optional, for JWT auth)
username?: string; // Username (for basic auth)
password?: string; // Password (for basic auth)
errors: string[]; // Validation errors
warnings: string[]; // Warnings
}
Enumeration of authentication method priorities:
`typescript`
enum AuthMethodPriority {
DESTINATION_BASED = 3, // Highest priority
DIRECT_JWT = 2, // Medium priority
BASIC = 1, // Lowest priority
NONE = 0 // Invalid/No auth
}
The validator provides detailed error messages for common issues:
- Missing required headers
- Invalid header values
- Empty header values (after trimming whitespace)
- Invalid URL format
- Invalid authentication type
- Missing authentication credentials
All errors are collected in the errors array, and the validation result includes isValid: false if any errors are present.
The validator issues warnings for:
- Conflicting headers (e.g., destination and direct JWT token both present)
- Multiple authentication methods with the same priority (should not happen in practice)
Warnings do not prevent validation from succeeding but indicate potential configuration issues.
`typescript
import { validateAuthHeaders } from '@mcp-abap-adt/header-validator';
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-sap-destination': 'S4HANA_E19',
};
const result = validateAuthHeaders(headers);
if (result.isValid && result.config) {
console.log('Using SAP destination-based auth');
console.log('Destination:', result.config.destination);
console.log('Priority:', result.config.priority);
console.log('Auth Type:', result.config.authType); // Always 'jwt'
}
`
`typescript
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-mcp-destination': 'TRIAL',
// Note: x-sap-auth-type not needed - always uses JWT
};
const result = validateAuthHeaders(headers);
if (result.isValid && result.config) {
console.log('Using MCP destination-based auth');
console.log('Destination:', result.config.destination);
}
`
`typescript
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'jwt',
'x-sap-jwt-token': 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
'x-sap-refresh-token': 'refresh_token',
};
const result = validateAuthHeaders(headers);
if (result.isValid && result.config) {
console.log('Using direct JWT auth');
console.log('Token:', result.config.jwtToken);
}
`
`typescript
const headers = {
'x-sap-url': 'https://test.sap.com',
'x-sap-auth-type': 'jwt',
// Missing required headers
};
const result = validateAuthHeaders(headers);
if (!result.isValid) {
console.error('Validation failed:');
result.errors.forEach(error => console.error( - ${error}));`
}
Complete documentation is available in the docs/` directory:
- Architecture - System architecture, priority system, and valid header combinations
- Development - Development guide and testing
- Usage - API reference and usage examples
See docs/README.md for the complete documentation index.
MIT