@mcp-abap-adt/header-validator

Header validator for MCP ABAP ADT - validates and prioritizes authentication headers.

Features

• ✅ 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

Responsibilities and Design Principles

Core Development Principle

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

Package Responsibilities

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

External Dependencies

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

Installation

npm install @mcp-abap-adt/header-validator

Usage

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);
}

Authentication Methods and Priorities

The validator supports four authentication methods, ordered by priority (highest to lowest):

1. SAP Destination-Based Authentication (Highest Priority)

Priority: AuthMethodPriority.SAP_DESTINATION (4)

Required Headers:

• x-sap-url - SAP system URL
• x-sap-destination - Destination name (e.g., "S4HANA_E19")

Optional Headers:

• x-sap-client - SAP client number
• x-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:

const headers = {
  'x-sap-url': 'https://test.sap.com',
  'x-sap-destination': 'S4HANA_E19',
};

Notes:

• Does NOT require x-sap-auth-type (always JWT)
• If x-sap-auth-type is provided, it will be ignored (warning issued)
• If x-sap-jwt-token is also provided, it will be ignored (warning issued)
• Requires AuthBroker to be initialized in the server
• Automatically handles token refresh and validation

2. MCP Destination-Based Authentication

Priority: AuthMethodPriority.MCP_DESTINATION (3)

Required Headers:

• x-sap-url - SAP system URL
• x-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:

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)
• If x-sap-auth-type is provided, it will be ignored (warning issued)
• If x-sap-jwt-token is also provided, it will be ignored (warning issued)
• Requires AuthBroker to be initialized in the server
• Automatically handles token refresh and validation

3. Direct JWT Authentication (Medium Priority)

Priority: AuthMethodPriority.DIRECT_JWT (2)

Required Headers:

• x-sap-url - SAP system URL
• x-sap-auth-type - Must be jwt or xsuaa
• x-sap-jwt-token - JWT access token

Optional Headers:

• x-sap-refresh-token - Refresh token for automatic token renewal
• x-sap-uaa-url / uaa-url - UAA URL
• x-sap-uaa-client-id / uaa-client-id - UAA Client ID
• x-sap-uaa-client-secret / uaa-client-secret - UAA Client Secret
• x-sap-client - SAP client number

Description: Direct JWT token authentication. Token is provided directly in headers.

Example:

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

4. Basic Authentication (Lowest Priority)

Priority: AuthMethodPriority.BASIC (1)

Required Headers:

• x-sap-url - SAP system URL
• x-sap-auth-type - Must be basic
• x-sap-login - Username
• x-sap-password - Password

Description: Basic HTTP authentication with username and password.

Example:

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)

Valid Header Combinations

✅ Valid Combinations

1. SAP Destination Only (Simplest - Recommended)

{
  'x-sap-url': 'https://test.sap.com',
  'x-sap-destination': 'S4HANA_E19',
}
// No x-sap-auth-type needed - always JWT

2. MCP Destination Only

{
  '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

{
  '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

{
  '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)

{
  '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)

{
  '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)

{
  '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

❌ Invalid Combinations

1. Missing Required Headers

{
  'x-sap-url': 'https://test.sap.com',
  // Missing x-sap-auth-type
}

Error: x-sap-auth-type header is required

2. Invalid Auth Type

{
  'x-sap-url': 'https://test.sap.com',
  'x-sap-auth-type': 'invalid',
}

Error: x-sap-auth-type must be one of: jwt, xsuaa, basic

3. JWT Auth Without Token or Destination

{
  'x-sap-url': 'https://test.sap.com',
  'x-sap-auth-type': 'jwt',
  // Missing x-sap-destination, x-mcp-destination, and x-sap-jwt-token
}

Error: JWT authentication requires either x-sap-destination, x-mcp-destination, or x-sap-jwt-token header

4. Basic Auth Without Credentials

{
  'x-sap-url': 'https://test.sap.com',
  'x-sap-auth-type': 'basic',
  // Missing x-sap-login and/or x-sap-password
}

Error: Basic authentication requires x-sap-login and x-sap-password headers

5. Empty Values

{
  'x-sap-url': 'https://test.sap.com',
  'x-sap-destination': '   ', // empty after trim
}

Error: x-sap-destination header is empty

6. Invalid URL

{
  'x-sap-url': 'not-a-valid-url',
  'x-sap-auth-type': 'jwt',
  'x-sap-jwt-token': 'token',
}

Error: x-sap-url is not a valid URL

Priority Resolution

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 present
2. MCP Destination (Priority 3) - Selected if x-mcp-destination is present (always uses JWT, no x-sap-auth-type needed)
3. Direct JWT (Priority 2) - Selected if JWT token is provided (requires x-sap-auth-type: jwt)
4. Basic (Priority 1) - Selected only if basic auth headers are present (requires x-sap-auth-type: basic)

Example: Priority Resolution

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"

API Reference

validateAuthHeaders(headers?: IncomingHttpHeaders): HeaderValidationResult

Validates and prioritizes authentication headers.

Parameters:

• headers - HTTP headers object (optional)

Returns: HeaderValidationResult object with:

• isValid: boolean - Whether the configuration is valid
• config?: ValidatedAuthConfig - Validated authentication configuration (if valid)
• errors: string[] - List of validation errors
• warnings: string[] - List of warnings (e.g., ignored headers)

ValidatedAuthConfig

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
}

AuthMethodPriority

Enumeration of authentication method priorities:

enum AuthMethodPriority {
  DESTINATION_BASED = 3,  // Highest priority
  DIRECT_JWT = 2,         // Medium priority
  BASIC = 1,              // Lowest priority
  NONE = 0                // Invalid/No auth
}

Error Handling

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.

Warnings

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.

Examples

Example 1: SAP Destination Auth (Simplest)

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'
}

Example 2: MCP Destination Auth

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);
}

Example 3: Direct JWT Auth

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);
}

Example 4: Error Handling

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}`));
}

Documentation

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.

License

MIT