# @mcp-abap-adt/header-validator

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

Latest version **0.3.0** (published 2026-09-24) · LGPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install @mcp-abap-adt/header-validator
pnpm add @mcp-abap-adt/header-validator
yarn add @mcp-abap-adt/header-validator
bun add @mcp-abap-adt/header-validator
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-09-24 |
| First published | 2025-11-30 |
| Weekly downloads | 0 |
| License | LGPL-3.0-only |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18.0.0 |
| Dependencies | 3 |
| Unpacked size | 100.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Oleksii Kyslytsia |
| Maintainers | fr0ster |
| Keywords | abap, sap, adt, mcp, header, validator, authentication, abap-adt |

## Links

- npm: https://www.npmjs.com/package/@mcp-abap-adt/header-validator
- Repository: https://github.com/fr0ster/mcp-abap-adt-header-validator
- Homepage: https://github.com/fr0ster/mcp-abap-adt-header-validator#readme
- Issues: https://github.com/fr0ster/mcp-abap-adt-header-validator/issues
- npm.io page: https://npm.io/package/@mcp-abap-adt/header-validator

## Dependencies (3)

- [@mcp-abap-adt/interfaces-auth](https://npm.io/package/@mcp-abap-adt/interfaces-auth.md) ^1.2.0
- [@mcp-abap-adt/interfaces-network](https://npm.io/package/@mcp-abap-adt/interfaces-network.md) ^2.0.0
- [@mcp-abap-adt/interfaces-auth-sap](https://npm.io/package/@mcp-abap-adt/interfaces-auth-sap.md) ^1.0.0

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 0.3.0 (latest) — 2026-09-24
- 0.1.8 — 2025-12-12
- 0.1.7 — 2025-12-07
- 0.1.6 — 2025-12-05
- 0.1.4 — 2025-12-04
- 0.1.3 — 2025-12-01
- 0.1.2 — 2025-11-30
- 0.1.1 — 2025-11-30
- 0.1.0 — 2025-11-30

## README

# @mcp-abap-adt/header-validator
[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)

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/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

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

## Usage

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

## 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**:
```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)
- 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**:
```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)
- 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**:
```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

### 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**:
```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)

## Valid Header Combinations

### ✅ Valid Combinations

#### 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

### ❌ Invalid Combinations

#### 1. Missing Required Headers
```typescript
{
  'x-sap-url': 'https://test.sap.com',
  // Missing x-sap-auth-type
}
```
**Error**: `x-sap-auth-type header is required`

#### 2. Invalid Auth Type
```typescript
{
  '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
```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
}
```
**Error**: `JWT authentication requires either x-sap-destination, x-mcp-destination, or x-sap-jwt-token header`

#### 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
}
```
**Error**: `Basic authentication requires x-sap-login and x-sap-password headers`

#### 5. Empty Values
```typescript
{
  'x-sap-url': 'https://test.sap.com',
  'x-sap-destination': '   ', // empty after trim
}
```
**Error**: `x-sap-destination header is empty`

#### 6. Invalid URL
```typescript
{
  '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

```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"
```

## 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`

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

### `AuthMethodPriority`

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

## 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)

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

### Example 2: MCP Destination Auth

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

### Example 3: Direct JWT Auth

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

### Example 4: Error Handling

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

## Documentation

Complete documentation is available in the [`docs/`](docs/) directory:

- **[Architecture](docs/architecture/ARCHITECTURE.md)** - System architecture, priority system, and valid header combinations
- **[Development](docs/development/DEVELOPMENT.md)** - Development guide and testing
- **[Usage](docs/using/USAGE.md)** - API reference and usage examples

See [docs/README.md](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.

Copyright © 2025–2026 Oleksii Kyslytsia

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`](LICENSE) is the
LGPL, [`COPYING`](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.

---
_Source: https://npm.io/package/@mcp-abap-adt/header-validator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._