0.3.0 • Published 10h ago

@mcp-abap-adt/header-validator

Licence

LGPL-3.0-only

Version

0.3.0

Deps

Size

100 kB

Vulns

Weekly

Summary Dependency Versions

@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

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:

Header validation: Validates authentication headers from HTTP requests
Priority resolution: Determines which authentication method to use based on header presence and priority rules
Configuration extraction: Extracts authentication configuration from headers
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/interfaces-network: every header name it validates, and the groups over them — a header name says how a value travels, not what it means, which is why they are there and not in the ADT contract
@mcp-abap-adt/interfaces-auth-sap: AuthType, AuthMethodPriority, IValidatedAuthConfig, IHeaderValidationResult, IAuthorizationConfig — what an SAP or BTP connection's authentication looks like once validated
@mcp-abap-adt/interfaces-auth: AUTH_TYPE_JWT and AUTH_TYPE_BASIC — a bearer token and a user with a password, which mean the same thing off SAP
Not @mcp-abap-adt/interfaces: that facade is deleted as of its 52.0.0. npm still serves 51.0.0 to anyone pinned to it, with every symbol re-exported and deprecated, and nothing further ships there
No dependency on an implementation package: all interactions happen through those contracts

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:

SAP Destination (Priority 4) - Always selected if x-sap-destination is present
MCP Destination (Priority 3) - Selected if x-mcp-destination is present (always uses JWT, no x-sap-auth-type needed)
Direct JWT (Priority 2) - Selected if JWT token is provided (requires x-sap-auth-type: jwt)
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

GNU Lesser General Public License v3.0 only (LGPL-3.0-only). Earlier published versions were MIT and stay MIT — a licence change is not retroactive.

This library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, version 3.

It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

Both texts ship with the package and both are needed: LICENSE is the LGPL, COPYING is the GPL it is written on top of, since the LGPL is a set of additional permissions over the GPL and cannot be read alone.

What this means if you depend on this package. Linking it into your own program — importing it, as every consumer of an npm package does — does not put your program under the LGPL. What the licence asks is that changes to this library stay free, and that your users can replace it with their own build.

Keywords

abap sap adt mcp header validator authentication abap-adt