@mcp-abap-adt/header-validator 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.4] - 2024-12-04
+
+### Added
+- **Interfaces Package Integration**: Migrated to use `@mcp-abap-adt/interfaces` package for all interface definitions
+  - All interfaces now imported from shared package
+  - Backward compatibility maintained with type aliases
+  - Dependency on `@mcp-abap-adt/interfaces@^0.1.0` added
+
+### Changed
+- **Interface Renaming**: Interfaces renamed to follow `I` prefix convention:
+  - `ValidatedAuthConfig` → `IValidatedAuthConfig` (type alias for backward compatibility)
+  - `HeaderValidationResult` → `IHeaderValidationResult` (type alias for backward compatibility)
+  - `AuthType` and `AuthMethodPriority` now imported from interfaces package
+  - Old names still work via type aliases for backward compatibility
+
+## [0.1.3] - 2025-12-01
+
+### Fixed
+- **x-mcp-destination validation** – fixed issue where `x-mcp-destination` header incorrectly required `x-sap-url`:
+  - `x-mcp-destination` now works identically to `x-sap-destination` - URL is automatically derived from service key
+  - `x-sap-url` is now optional for `x-mcp-destination` (and will be ignored with a warning if provided)
+  - Fixed validation logic to check `x-mcp-destination` immediately after `x-sap-destination`, regardless of `x-sap-url` presence
+  - This fixes issues on Windows where `x-mcp-destination` was being ignored
+
+### Changed
+- **Header case handling** – improved header value extraction to check both lowercase and original case:
+  - `getHeaderValue()` now checks lowercase first (Node.js normalizes headers), then original case for compatibility
+  - Both `validateSapDestinationAuth()` and `validateMcpDestinationAuth()` check headers in both cases
+  - Better cross-platform compatibility, especially for Windows
+
+- **Validation order** – improved validation priority logic:
+  - `x-mcp-destination` is now checked immediately after `x-sap-destination`, before checking for `x-sap-url`
+  - This ensures destination-based authentication is prioritized correctly
+  - URL validation only happens for non-destination authentication methods
+
+- **Documentation updates** – updated architecture documentation:
+  - Updated `ARCHITECTURE.md` to reflect that `x-sap-url` is not required for `x-mcp-destination`
+  - Updated `PRIORITY_DIAGRAM.md` with correct header requirements
+  - Updated examples to show `x-mcp-destination` without `x-sap-url`
+
+### Added
+- **Test coverage** – added tests for new validation behavior:
+  - Test for `x-mcp-destination` without `x-sap-url` (should work)
+  - Test for warning when `x-sap-url` is provided with `x-mcp-destination`
+  - Updated existing tests to reflect new validation logic
+
 ## [0.1.2] - 2025-11-30
 
 ### Changed

package/README.md

@@ -9,6 +9,56 @@ Header validator for MCP ABAP ADT - validates and prioritizes authentication hea
 - ✅ **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
 
 ```bash

package/dist/headerValidator.d.ts

@@ -7,7 +7,7 @@
  * 3. Basic auth (x-sap-login + x-sap-password) - lowest priority
  */
 import { IncomingHttpHeaders } from 'http';
-import { HeaderValidationResult } from './types';
+import type { HeaderValidationResult } from './types';
 /**
  * Validate and prioritize authentication headers
  *

package/dist/headerValidator.js

@@ -9,12 +9,18 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateAuthHeaders = validateAuthHeaders;
-const types_1 = require("./types");
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
 /**
  * Extract header value (handles array values)
+ * Node.js normalizes headers to lowercase, but check both cases for safety
  */
 function getHeaderValue(headers, name) {
-    const value = headers[name];
+    // Try lowercase first (Node.js normalizes to lowercase)
+    let value = headers[name.toLowerCase()];
+    // If not found, try original case (for compatibility)
+    if (!value) {
+        value = headers[name];
+    }
     if (!value) {
         return undefined;
     }
@@ -41,7 +47,8 @@ function isValidUrl(url) {
  * URL is taken from destination (service key or .env), not from x-sap-url header
  */
 function validateSapDestinationAuth(headers) {
-    const destinationRaw = headers['x-sap-destination'];
+    // Check both lowercase and original case (Node.js normalizes to lowercase, but check both for safety)
+    const destinationRaw = headers['x-sap-destination'] || headers['X-SAP-Destination'];
     if (!destinationRaw) {
         return null;
     }
@@ -52,7 +59,7 @@ function validateSapDestinationAuth(headers) {
     if (!destination || destination.length === 0) {
         errors.push('x-sap-destination header is empty');
         return {
-            priority: types_1.AuthMethodPriority.NONE,
+            priority: interfaces_1.AuthMethodPriority.NONE,
             authType: 'jwt', // SAP destination always uses JWT
             sapUrl: '', // URL will be loaded from destination
             errors,
@@ -80,7 +87,7 @@ function validateSapDestinationAuth(headers) {
         warnings.push('x-sap-auth-type is ignored when x-sap-destination is present (always uses JWT)');
     }
     return {
-        priority: types_1.AuthMethodPriority.SAP_DESTINATION,
+        priority: interfaces_1.AuthMethodPriority.SAP_DESTINATION,
         authType: 'jwt', // Always JWT for x-sap-destination
         sapUrl: '', // URL will be loaded from destination (service key or .env)
         sapClient,
@@ -94,10 +101,12 @@ function validateSapDestinationAuth(headers) {
 /**
  * Validate MCP destination-based authentication (medium-high priority)
  * x-mcp-destination - uses AuthBroker, always JWT (no x-sap-auth-type needed)
- * x-sap-url is required for MCP destination (unlike x-sap-destination)
+ * URL is taken from destination (service key or .env), not from x-sap-url header
+ * x-sap-url is optional - if provided, it will be ignored (warning issued)
  */
 function validateMcpDestinationAuth(headers, sapUrl) {
-    const destinationRaw = headers['x-mcp-destination'];
+    // Check both lowercase and original case (Node.js normalizes to lowercase, but check both for safety)
+    const destinationRaw = headers['x-mcp-destination'] || headers['X-MCP-Destination'];
     if (!destinationRaw) {
         return null;
     }
@@ -108,23 +117,16 @@ function validateMcpDestinationAuth(headers, sapUrl) {
     if (!destination || destination.length === 0) {
         errors.push('x-mcp-destination header is empty');
         return {
-            priority: types_1.AuthMethodPriority.NONE,
+            priority: interfaces_1.AuthMethodPriority.NONE,
             authType: 'jwt', // MCP destination always uses JWT
-            sapUrl: sapUrl || '',
+            sapUrl: '', // URL will be loaded from destination
             errors,
             warnings,
         };
     }
-    // x-sap-url is required for MCP destination
-    if (!sapUrl) {
-        errors.push('x-sap-url header is required when x-mcp-destination is present');
-        return {
-            priority: types_1.AuthMethodPriority.NONE,
-            authType: 'jwt',
-            sapUrl: '',
-            errors,
-            warnings,
-        };
+    // Warning if x-sap-url is provided (URL comes from destination, not header)
+    if (sapUrl) {
+        warnings.push('x-sap-url is ignored when x-mcp-destination is present (URL is loaded from destination service key or .env file)');
     }
     // Warning if x-sap-auth-type is provided (not needed for x-mcp-destination)
     const authType = getHeaderValue(headers, 'x-sap-auth-type');
@@ -139,9 +141,9 @@ function validateMcpDestinationAuth(headers, sapUrl) {
         warnings.push('x-sap-jwt-token is ignored when x-mcp-destination is present (destination-based auth takes priority)');
     }
     return {
-        priority: types_1.AuthMethodPriority.MCP_DESTINATION,
+        priority: interfaces_1.AuthMethodPriority.MCP_DESTINATION,
         authType: 'jwt', // Always JWT for x-mcp-destination
-        sapUrl,
+        sapUrl: '', // URL will be loaded from destination (service key or .env)
         sapClient,
         destination,
         errors,
@@ -173,7 +175,7 @@ function validateDirectJwtAuth(headers, sapUrl, authType) {
     // Extract optional SAP client
     const sapClient = getHeaderValue(headers, 'x-sap-client');
     return {
-        priority: types_1.AuthMethodPriority.DIRECT_JWT,
+        priority: interfaces_1.AuthMethodPriority.DIRECT_JWT,
         authType,
         sapUrl,
         sapClient,
@@ -212,7 +214,7 @@ function validateBasicAuth(headers, sapUrl, authType) {
     // Return config with errors if validation failed
     if (errors.length > 0) {
         return {
-            priority: types_1.AuthMethodPriority.NONE,
+            priority: interfaces_1.AuthMethodPriority.NONE,
             authType,
             sapUrl,
             errors,
@@ -220,7 +222,7 @@ function validateBasicAuth(headers, sapUrl, authType) {
         };
     }
     return {
-        priority: types_1.AuthMethodPriority.BASIC,
+        priority: interfaces_1.AuthMethodPriority.BASIC,
         authType,
         sapUrl,
         username,
@@ -267,53 +269,48 @@ function validateAuthHeaders(headers) {
             };
         }
     }
-    // For other auth methods, x-sap-url is required (but MCP destination can work without it if URL is optional)
+    // Check for MCP destination (doesn't require x-sap-url, URL comes from destination)
     const sapUrl = getHeaderValue(headers, 'x-sap-url');
-    // Check for MCP destination (requires x-sap-url header)
-    if (sapUrl) {
-        // Validate URL format first
-        if (!isValidUrl(sapUrl)) {
-            errors.push(`x-sap-url is not a valid URL: ${sapUrl}`);
+    const mcpDestinationConfig = validateMcpDestinationAuth(headers, sapUrl);
+    if (mcpDestinationConfig) {
+        // MCP destination found - URL comes from destination, not header
+        if (mcpDestinationConfig.errors.length === 0) {
             return {
-                isValid: false,
-                errors,
-                warnings,
+                isValid: true,
+                config: mcpDestinationConfig,
+                errors: [],
+                warnings: mcpDestinationConfig.warnings,
             };
         }
-        const mcpDestinationConfig = validateMcpDestinationAuth(headers, sapUrl);
-        if (mcpDestinationConfig) {
-            if (mcpDestinationConfig.errors.length === 0) {
-                return {
-                    isValid: true,
-                    config: mcpDestinationConfig,
-                    errors: [],
-                    warnings: mcpDestinationConfig.warnings,
-                };
-            }
-            else {
-                return {
-                    isValid: false,
-                    errors: mcpDestinationConfig.errors,
-                    warnings: mcpDestinationConfig.warnings,
-                };
-            }
+        else {
+            // Has errors, continue to check other methods or return error
+            return {
+                isValid: false,
+                errors: mcpDestinationConfig.errors,
+                warnings: mcpDestinationConfig.warnings,
+            };
         }
     }
-    // If no auth headers at all, return empty result (not an error - may use .env file)
+    // For other auth methods, x-sap-url is required
     if (!sapUrl) {
+        // If no auth headers at all, return empty result (not an error - may use .env file)
         return {
             isValid: false,
             errors: [],
             warnings: [],
         };
     }
+    // Validate URL format
+    if (!isValidUrl(sapUrl)) {
+        errors.push(`x-sap-url is not a valid URL: ${sapUrl}`);
+        return {
+            isValid: false,
+            errors,
+            warnings,
+        };
+    }
     // Try to validate authentication methods in priority order
     const configs = [];
-    // 2. MCP destination-based auth (medium-high priority) - doesn't require x-sap-auth-type
-    const mcpDestinationConfig = validateMcpDestinationAuth(headers, sapUrl);
-    if (mcpDestinationConfig) {
-        configs.push(mcpDestinationConfig);
-    }
     // 3. Other auth methods require x-sap-auth-type
     const sapAuthType = getHeaderValue(headers, 'x-sap-auth-type');
     if (sapAuthType) {
@@ -357,9 +354,12 @@ function validateAuthHeaders(headers) {
                 errors.push('Basic authentication requires x-sap-login and x-sap-password headers');
             }
         }
-        else if (mcpDestinationConfig && mcpDestinationConfig.errors.length > 0) {
-            // MCP destination was found but has errors
-            errors.push(...mcpDestinationConfig.errors);
+        else {
+            // Check if MCP destination was found but has errors
+            const mcpConfig = validateMcpDestinationAuth(headers, sapUrl);
+            if (mcpConfig && mcpConfig.errors.length > 0) {
+                errors.push(...mcpConfig.errors);
+            }
         }
         return {
             isValid: false,
@@ -372,7 +372,7 @@ function validateAuthHeaders(headers) {
     // Check for conflicts (multiple auth methods with same priority shouldn't happen, but check anyway)
     const samePriorityConfigs = configs.filter(c => c.priority === selectedConfig.priority);
     if (samePriorityConfigs.length > 1) {
-        warnings.push(`Multiple authentication methods with same priority detected, using: ${types_1.AuthMethodPriority[selectedConfig.priority]}`);
+        warnings.push(`Multiple authentication methods with same priority detected, using: ${interfaces_1.AuthMethodPriority[selectedConfig.priority]}`);
     }
     // Merge errors and warnings
     const allErrors = [...errors, ...selectedConfig.errors];

package/dist/types.d.ts

@@ -1,64 +1,9 @@
 /**
  * Types for header validator
  */
-/**
- * Authentication type
- */
-export type AuthType = 'jwt' | 'xsuaa' | 'basic';
-/**
- * Authentication method priority
- * Higher number = higher priority
- */
-export declare enum AuthMethodPriority {
-    SAP_DESTINATION = 4,// x-sap-destination (uses AuthBroker, JWT only)
-    MCP_DESTINATION = 3,// x-mcp-destination + x-sap-auth-type=jwt (uses AuthBroker)
-    DIRECT_JWT = 2,// x-sap-jwt-token + x-sap-auth-type=jwt
-    BASIC = 1,// x-sap-login + x-sap-password + x-sap-auth-type=basic
-    NONE = 0
-}
-/**
- * Validated authentication configuration
- */
-export interface ValidatedAuthConfig {
-    /** Authentication method priority */
-    priority: AuthMethodPriority;
-    /** Authentication type */
-    authType: AuthType;
-    /** SAP URL */
-    sapUrl: string;
-    /** SAP Client (optional) */
-    sapClient?: string;
-    /** Destination name (for destination-based auth: x-sap-destination or x-mcp-destination) */
-    destination?: string;
-    /** JWT token (for direct JWT auth) */
-    jwtToken?: string;
-    /** Refresh token (optional, for JWT auth) */
-    refreshToken?: string;
-    /** UAA URL (optional, for JWT auth) */
-    uaaUrl?: string;
-    /** UAA Client ID (optional, for JWT auth) */
-    uaaClientId?: string;
-    /** UAA Client Secret (optional, for JWT auth) */
-    uaaClientSecret?: string;
-    /** Username (for basic auth) */
-    username?: string;
-    /** Password (for basic auth) */
-    password?: string;
-    /** Validation errors (if any) */
-    errors: string[];
-    /** Warnings (if any) */
-    warnings: string[];
-}
-/**
- * Header validation result
- */
-export interface HeaderValidationResult {
-    /** Is configuration valid? */
-    isValid: boolean;
-    /** Validated authentication configuration */
-    config?: ValidatedAuthConfig;
-    /** Validation errors */
-    errors: string[];
-    /** Warnings */
-    warnings: string[];
-}
+import type { AuthType } from '@mcp-abap-adt/interfaces';
+import { AuthMethodPriority, type IValidatedAuthConfig, type IHeaderValidationResult } from '@mcp-abap-adt/interfaces';
+export type { AuthType };
+export { AuthMethodPriority };
+export type ValidatedAuthConfig = IValidatedAuthConfig;
+export type HeaderValidationResult = IHeaderValidationResult;

package/dist/types.js

@@ -4,15 +4,5 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthMethodPriority = void 0;
-/**
- * Authentication method priority
- * Higher number = higher priority
- */
-var AuthMethodPriority;
-(function (AuthMethodPriority) {
-    AuthMethodPriority[AuthMethodPriority["SAP_DESTINATION"] = 4] = "SAP_DESTINATION";
-    AuthMethodPriority[AuthMethodPriority["MCP_DESTINATION"] = 3] = "MCP_DESTINATION";
-    AuthMethodPriority[AuthMethodPriority["DIRECT_JWT"] = 2] = "DIRECT_JWT";
-    AuthMethodPriority[AuthMethodPriority["BASIC"] = 1] = "BASIC";
-    AuthMethodPriority[AuthMethodPriority["NONE"] = 0] = "NONE"; // No valid authentication
-})(AuthMethodPriority || (exports.AuthMethodPriority = AuthMethodPriority = {}));
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
+Object.defineProperty(exports, "AuthMethodPriority", { enumerable: true, get: function () { return interfaces_1.AuthMethodPriority; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/header-validator",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Header validator for MCP ABAP ADT - validates and prioritizes authentication headers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,6 +44,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "@mcp-abap-adt/interfaces": "^0.1.0"
+  },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^24.2.1",