@mcp-abap-adt/proxy 2.0.0 → 4.0.0

package/dist/proxy/credentials.d.ts

@@ -0,0 +1,45 @@
+import { TokenAuthProvider } from '@mcp-abap-adt/connection';
+import type { ITokenRefresher } from '@mcp-abap-adt/interfaces-auth';
+/**
+ * What a destination authenticates with, and where its requests go.
+ *
+ * The credential is the ecosystem's shared one — `TokenAuthProvider` over the
+ * broker's `ITokenRefresher`. It is asked for a header per request and renews
+ * behind that call, which is why nothing here caches a token, decodes a JWT
+ * `exp`, or runs a refresh timer. All three used to live in `BtpProxy` and all
+ * three duplicated the broker, the last one by holding a `setTimeout` per
+ * destination for the life of the process.
+ */
+export interface DestinationAccess {
+    readonly credential: TokenAuthProvider;
+    /** From the service key. `undefined` when it carries none. */
+    readonly baseUrl: string | undefined;
+}
+/**
+ * The part of `AuthBroker` this needs, named rather than taken whole.
+ *
+ * Two methods is the entire seam, so a test states two methods instead of
+ * standing up a broker with a service-key store behind it.
+ */
+export interface CredentialSource {
+    createTokenRefresher(destination: string): ITokenRefresher;
+    getConnectionConfig(destination: string): Promise<{
+        serviceUrl?: string;
+    } | null>;
+}
+export type BrokerFor = (destination: string) => Promise<CredentialSource>;
+export declare class DestinationCredentials {
+    private readonly brokerFor;
+    /**
+     * The promise is held, not the result, so concurrent first requests for one
+     * destination share a single build instead of racing to make two credentials
+     * and two brokers.
+     */
+    private readonly held;
+    constructor(brokerFor: BrokerFor);
+    get(destination: string): Promise<DestinationAccess>;
+    private build;
+    /** Drop everything held. Nothing here outlives a stop. */
+    clear(): void;
+}
+//# sourceMappingURL=credentials.d.ts.map

package/dist/proxy/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/proxy/credentials.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAAC;IAC3D,mBAAmB,CACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC5C;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE3E,qBAAa,sBAAsB;IAQrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAPtC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiD;gBAEzC,SAAS,EAAE,SAAS;IAEjD,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;YActC,KAAK;IASnB,0DAA0D;IAC1D,KAAK,IAAI,IAAI;CAGd"}

package/dist/proxy/credentials.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DestinationCredentials = void 0;
+// src/proxy/credentials.ts
+const connection_1 = require("@mcp-abap-adt/connection");
+class DestinationCredentials {
+    brokerFor;
+    /**
+     * The promise is held, not the result, so concurrent first requests for one
+     * destination share a single build instead of racing to make two credentials
+     * and two brokers.
+     */
+    held = new Map();
+    constructor(brokerFor) {
+        this.brokerFor = brokerFor;
+    }
+    get(destination) {
+        const existing = this.held.get(destination);
+        if (existing)
+            return existing;
+        const pending = this.build(destination).catch((error) => {
+            // A rejected promise left in the map would serve the failure forever: a
+            // service key added after the first miss would never be seen.
+            this.held.delete(destination);
+            throw error;
+        });
+        this.held.set(destination, pending);
+        return pending;
+    }
+    async build(destination) {
+        const broker = await this.brokerFor(destination);
+        const credential = new connection_1.TokenAuthProvider(broker.createTokenRefresher(destination));
+        const connection = await broker.getConnectionConfig(destination);
+        return { credential, baseUrl: connection?.serviceUrl };
+    }
+    /** Drop everything held. Nothing here outlives a stop. */
+    clear() {
+        this.held.clear();
+    }
+}
+exports.DestinationCredentials = DestinationCredentials;

package/dist/proxy/requestHandler.d.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** The part of `BtpProxy` a forwarded request needs. */
+export interface CredentialFacade {
+    getAuthorizationHeader(destination: string): Promise<string | null>;
+    getTargetUrl(destination: string): Promise<string>;
+}
+export interface ProxyRequestHandlerOptions {
+    config: {
+        btpDestination?: string;
+        targetUrl?: string;
+        defaultHeaders?: Record<string, string>;
+    };
+    /** Asked per request; the caller decides whether to build or reuse. */
+    proxy: () => Promise<CredentialFacade>;
+    /**
+     * What an AUTHENTICATION failure means here — and it is a parameter because
+     * the two callers disagree.
+     *
+     * The standalone proxy treats it as fatal and exits, so whatever started it
+     * can start it again with a credential that works. The MCP mode must not:
+     * exiting there takes the MCP server down with it, and the client's session
+     * with that. Left out, the failure is simply answered and the process lives.
+     *
+     * A failure to FORWARD never reaches this. A dead backend is not a credential
+     * problem, and treating it as one is how a proxy ends up exiting over
+     * someone else's outage.
+     */
+    onAuthFailure?: (error: unknown, destination: string) => Promise<void> | void;
+}
+/**
+ * The request path, in one place: analyse, authenticate, forward.
+ *
+ * It was a closure inside the standalone server, which is where it could stay
+ * while there was one caller. The MCP mode is the second, and a copy of this
+ * flow over there would be two places for the routing rules to drift apart.
+ */
+export declare function createProxyRequestHandler(options: ProxyRequestHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=requestHandler.d.ts.map

package/dist/proxy/requestHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestHandler.d.ts","sourceRoot":"","sources":["../../src/proxy/requestHandler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMjE,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpE,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE;QACN,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACzC,CAAC;IACF,uEAAuE;IACvE,KAAK,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACvC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CA8E9D"}

package/dist/proxy/requestHandler.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProxyRequestHandler = createProxyRequestHandler;
+const logger_js_1 = require("../lib/logger.js");
+const headerAnalyzer_js_1 = require("../router/headerAnalyzer.js");
+const requestInterceptor_js_1 = require("../router/requestInterceptor.js");
+const reverseProxy_js_1 = require("./reverseProxy.js");
+/**
+ * The request path, in one place: analyse, authenticate, forward.
+ *
+ * It was a closure inside the standalone server, which is where it could stay
+ * while there was one caller. The MCP mode is the second, and a copy of this
+ * flow over there would be two places for the routing rules to drift apart.
+ */
+function createProxyRequestHandler(options) {
+    const { config, proxy, onAuthFailure } = options;
+    return async function handle(req, res) {
+        const intercepted = (0, requestInterceptor_js_1.interceptRequest)(req, undefined, { btpDestination: config.btpDestination, targetUrl: config.targetUrl }, { skipHeaderValidation: true });
+        if (intercepted.routingDecision.strategy === headerAnalyzer_js_1.RoutingStrategy.UNKNOWN) {
+            logger_js_1.logger?.error('Routing decision failed', {
+                type: 'ROUTING_DECISION_FAILED',
+                reason: intercepted.routingDecision.reason,
+            });
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: intercepted.routingDecision.reason }));
+            return;
+        }
+        const destination = intercepted.routingDecision.btpDestination;
+        if (!destination) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No BTP destination specified' }));
+            return;
+        }
+        const facade = await proxy();
+        // Authentication is separated from forwarding on purpose: the two failures
+        // mean different things, and only one of them is about us.
+        let authorization;
+        try {
+            authorization = await facade.getAuthorizationHeader(destination);
+        }
+        catch (authError) {
+            logger_js_1.logger?.error('Proxy request failed: authentication error', {
+                type: 'PROXY_REQUEST_AUTH_ERROR',
+                destination,
+                error: authError instanceof Error ? authError.message : String(authError),
+            });
+            if (!res.headersSent) {
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Authentication failed' }));
+            }
+            await onAuthFailure?.(authError, destination);
+            return;
+        }
+        try {
+            const targetUrl = intercepted.routingDecision.targetUrl ||
+                (await facade.getTargetUrl(destination));
+            await (0, reverseProxy_js_1.forwardRequest)(req, res, targetUrl, authorization, config.defaultHeaders);
+        }
+        catch (error) {
+            logger_js_1.logger?.error('Proxy request failed', {
+                type: 'PROXY_REQUEST_ERROR',
+                destination,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent) {
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: error instanceof Error ? error.message : 'Proxy error',
+                }));
+            }
+        }
+    };
+}

package/dist/proxy/reverseProxy.d.ts

@@ -1,7 +1,16 @@
 import * as http from 'node:http';
 /**
- * Forward an HTTP request to a target URL with JWT injection.
+ * Forward an HTTP request to a target URL, with the credential's header.
  * Streams both request and response using pipe().
+ *
+ * `authorization` is a complete header VALUE, not a token: it is what
+ * `IAuthProvider.authorizationHeader()` answers, `Bearer <token>` and all.
+ * Composing `Bearer` here as well would send `Bearer Bearer <token>`.
+ *
+ * `requestBody` is for a caller that has already read the request: the SSE path
+ * parses the JSON-RPC body because an error envelope has to echo its `id`, and
+ * a stream read once cannot be piped. The RESPONSE still streams either way,
+ * which is the direction that carries an event stream.
  */
-export declare function forwardRequest(clientReq: http.IncomingMessage, clientRes: http.ServerResponse, targetBaseUrl: string, jwtToken: string, defaultHeaders?: Record<string, string>): Promise<void>;
+export declare function forwardRequest(clientReq: http.IncomingMessage, clientRes: http.ServerResponse, targetBaseUrl: string, authorization: string | null, defaultHeaders?: Record<string, string>, requestBody?: Buffer): Promise<void>;
 //# sourceMappingURL=reverseProxy.d.ts.map

package/dist/proxy/reverseProxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reverseProxy.d.ts","sourceRoot":"","sources":["../../src/proxy/reverseProxy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAoBlC;;;GAGG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,IAAI,CAAC,eAAe,EAC/B,SAAS,EAAE,IAAI,CAAC,cAAc,EAC9B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAiGf"}
+{"version":3,"file":"reverseProxy.d.ts","sourceRoot":"","sources":["../../src/proxy/reverseProxy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAoBlC;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,IAAI,CAAC,eAAe,EAC/B,SAAS,EAAE,IAAI,CAAC,cAAc,EAC9B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAkIf"}

package/dist/proxy/reverseProxy.js

@@ -54,10 +54,19 @@ const HOP_BY_HOP_HEADERS = new Set([
     'host',
 ]);
 /**
- * Forward an HTTP request to a target URL with JWT injection.
+ * Forward an HTTP request to a target URL, with the credential's header.
  * Streams both request and response using pipe().
+ *
+ * `authorization` is a complete header VALUE, not a token: it is what
+ * `IAuthProvider.authorizationHeader()` answers, `Bearer <token>` and all.
+ * Composing `Bearer` here as well would send `Bearer Bearer <token>`.
+ *
+ * `requestBody` is for a caller that has already read the request: the SSE path
+ * parses the JSON-RPC body because an error envelope has to echo its `id`, and
+ * a stream read once cannot be piped. The RESPONSE still streams either way,
+ * which is the direction that carries an event stream.
  */
-async function forwardRequest(clientReq, clientRes, targetBaseUrl, jwtToken, defaultHeaders) {
+async function forwardRequest(clientReq, clientRes, targetBaseUrl, authorization, defaultHeaders, requestBody) {
     const targetUrl = new node_url_1.URL(clientReq.url || '/', targetBaseUrl);
     // Build forwarded headers: defaults first, then client headers override
     const forwardedHeaders = {};
@@ -77,9 +86,18 @@ async function forwardRequest(clientReq, clientRes, targetBaseUrl, jwtToken, def
             forwardedHeaders[key] = value;
         }
     }
-    // Inject JWT
-    if (jwtToken) {
-        forwardedHeaders.authorization = `Bearer ${jwtToken}`;
+    // The credential's header, verbatim.
+    //
+    // `null` means this credential is not a header at all — a certificate
+    // authenticates through TLS and has none — and must reach the target as an
+    // ABSENT header rather than an empty one, which is a different claim.
+    //
+    // `''` is treated the same way. The contract calls the empty string a legal
+    // header value, but the provider that answers it here returns it for "no
+    // token", not for "an empty Authorization" — and that is also what this
+    // function did before it carried header values.
+    if (authorization) {
+        forwardedHeaders.authorization = authorization;
     }
     // Set correct host for target
     forwardedHeaders.host = targetUrl.host;
@@ -106,6 +124,13 @@ async function forwardRequest(clientReq, clientRes, targetBaseUrl, jwtToken, def
         target: targetUrl.toString(),
     });
     return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        };
         const proxyReq = transport.request(options, (proxyRes) => {
             // Forward status code
             const statusCode = proxyRes.statusCode || 502;
@@ -125,7 +150,19 @@ async function forwardRequest(clientReq, clientRes, targetBaseUrl, jwtToken, def
             });
             clientRes.writeHead(statusCode, responseHeaders);
             proxyRes.pipe(clientRes);
-            proxyRes.on('end', resolve);
+            proxyRes.on('end', finish);
+        });
+        // The client going away has to take the upstream with it.
+        //
+        // A stop destroys the CLIENT socket — `closeAllConnections()` — and nothing
+        // here destroyed the other one, so an abandoned event stream left a live
+        // connection to the target: a released port reported while a socket was
+        // still held, accumulating across repeated start/stop. It also left this
+        // promise pending forever, since `proxyRes` never ends.
+        clientRes.on('close', () => {
+            if (!settled)
+                proxyReq.destroy();
+            finish();
         });
         proxyReq.on('error', (err) => {
             logger_js_1.logger?.error('Reverse proxy connection error', {
@@ -137,9 +174,15 @@ async function forwardRequest(clientReq, clientRes, targetBaseUrl, jwtToken, def
                 clientRes.writeHead(502, { 'Content-Type': 'application/json' });
                 clientRes.end(JSON.stringify({ error: `Proxy error: ${err.message}` }));
             }
-            resolve();
+            finish();
         });
-        // Pipe client request body to backend
-        clientReq.pipe(proxyReq);
+        // Pipe client request body to backend — or write what the caller already
+        // read off it, since a spent stream pipes nothing.
+        if (requestBody === undefined) {
+            clientReq.pipe(proxyReq);
+        }
+        else {
+            proxyReq.end(requestBody);
+        }
     });
 }

package/dist/router/headerAnalyzer.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RoutingStrategy = void 0;
 exports.analyzeHeaders = analyzeHeaders;
 exports.shouldProxy = shouldProxy;
-const interfaces_1 = require("@mcp-abap-adt/interfaces");
+const interfaces_network_1 = require("@mcp-abap-adt/interfaces-network");
 const logger_js_1 = require("../lib/logger.js");
 var RoutingStrategy;
 (function (RoutingStrategy) {
@@ -50,7 +50,7 @@ function analyzeHeaders(headers, configOverrides) {
     };
     // Extract authorization destination for BTP Cloud (x-sap-destination)
     // Command-line parameter --btp takes precedence over header
-    const btpDestinationHeader = getHeaderValue(interfaces_1.HEADER_SAP_DESTINATION);
+    const btpDestinationHeader = getHeaderValue(interfaces_network_1.HEADER_SAP_DESTINATION);
     const extractedBtpDestination = configOverrides?.btpDestination
         ? configOverrides.btpDestination
         : btpDestinationHeader;

package/dist/router/requestInterceptor.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.interceptRequest = interceptRequest;
 exports.sanitizeHeadersForLogging = sanitizeHeadersForLogging;
 const header_validator_1 = require("@mcp-abap-adt/header-validator");
-const interfaces_1 = require("@mcp-abap-adt/interfaces");
+const interfaces_network_1 = require("@mcp-abap-adt/interfaces-network");
 const logger_js_1 = require("../lib/logger.js");
 const headerAnalyzer_js_1 = require("./headerAnalyzer.js");
 /**
@@ -38,9 +38,9 @@ function interceptRequest(req, body, configOverrides, options) {
         }
     }
     // Extract session ID if present
-    const sessionId = (req.headers[interfaces_1.HEADER_SESSION_ID] ||
-        req.headers[interfaces_1.HEADER_MCP_SESSION_ID] ||
-        req.headers[interfaces_1.HEADER_X_MCP_SESSION_ID]);
+    const sessionId = (req.headers[interfaces_network_1.HEADER_SESSION_ID] ||
+        req.headers[interfaces_network_1.HEADER_MCP_SESSION_ID] ||
+        req.headers[interfaces_network_1.HEADER_X_MCP_SESSION_ID]);
     // Generate client ID
     const clientId = `${req.socket.remoteAddress}:${req.socket.remotePort}`;
     // Log intercepted request
@@ -69,11 +69,11 @@ function interceptRequest(req, body, configOverrides, options) {
 function sanitizeHeadersForLogging(headers) {
     const sanitized = {};
     const sensitiveKeys = [
-        interfaces_1.HEADER_AUTHORIZATION,
-        interfaces_1.HEADER_SAP_JWT_TOKEN,
-        interfaces_1.HEADER_SAP_REFRESH_TOKEN,
-        interfaces_1.HEADER_SAP_PASSWORD,
-        interfaces_1.HEADER_SAP_UAA_CLIENT_SECRET,
+        interfaces_network_1.HEADER_AUTHORIZATION,
+        interfaces_network_1.HEADER_SAP_JWT_TOKEN,
+        interfaces_network_1.HEADER_SAP_REFRESH_TOKEN,
+        interfaces_network_1.HEADER_SAP_PASSWORD,
+        interfaces_network_1.HEADER_SAP_UAA_CLIENT_SECRET,
     ].map((k) => k.toLowerCase());
     for (const [key, value] of Object.entries(headers)) {
         if (sensitiveKeys.includes(key.toLowerCase())) {

package/docs/API.md

@@ -0,0 +1,172 @@
+# API Documentation
+
+This document describes the API and interfaces provided by `@mcp-abap-adt/proxy`.
+
+## Server Class
+
+### `McpAbapAdtProxyServer`
+
+Main server class for the MCP ABAP ADT Proxy.
+
+#### Constructor
+
+```typescript
+constructor(transportConfig?: TransportConfig, configPath?: string)
+```
+
+**Parameters:**
+- `transportConfig` (optional): Transport configuration. If not provided, parsed from command line arguments and environment variables.
+- `configPath` (optional): Path to configuration file. If not provided, searches default locations.
+
+**Example:**
+```typescript
+import { McpAbapAdtProxyServer } from "@mcp-abap-adt/proxy";
+
+const server = new McpAbapAdtProxyServer();
+await server.run();
+```
+
+#### Methods
+
+##### `run(): Promise<void>`
+
+Starts the proxy server and connects it to the transport.
+
+**Returns:** Promise that resolves when server is started.
+
+**Example:**
+```typescript
+await server.run();
+```
+
+##### `shutdown(): Promise<void>`
+
+Gracefully shuts down the server and closes all connections.
+
+**Returns:** Promise that resolves when server is shut down.
+
+**Example:**
+```typescript
+await server.shutdown();
+```
+
+## Router Modules
+
+### Header Analyzer
+
+#### `analyzeHeaders(headers: IncomingHttpHeaders, configOverrides?: { btpDestination?: string; targetUrl?: string }): RoutingDecision`
+
+Analyzes HTTP headers to determine routing strategy. CLI overrides (`--btp`, `--target-url`) take precedence over headers.
+
+**Parameters:**
+- `headers`: HTTP request headers
+- `configOverrides`: optional `btpDestination` / `targetUrl` from CLI params
+
+**Returns:** `RoutingDecision` object with routing strategy and metadata.
+
+**Example:**
+```typescript
+import { analyzeHeaders } from "@mcp-abap-adt/proxy/router/headerAnalyzer";
+
+const decision = analyzeHeaders(req.headers, { btpDestination: "ai" });
+console.log(decision.strategy); // "proxy" | "unknown"
+console.log(decision.btpDestination); // Destination for BTP Cloud authorization (from header or override)
+console.log(decision.targetUrl); // Explicit target URL (from x-target-url or override)
+```
+
+#### Routing Strategies
+
+- `PROXY`: Proxy request with JWT authentication (`x-sap-destination` / `--btp` present)
+- `UNKNOWN`: No BTP destination provided — request cannot be routed
+
+### Request Interceptor
+
+#### `interceptRequest(req: IncomingMessage, body?: any): InterceptedRequest`
+
+Intercepts and analyzes incoming HTTP request.
+
+**Parameters:**
+- `req`: HTTP request object
+- `body`: Optional request body
+
+**Returns:** `InterceptedRequest` object with routing decision and metadata.
+
+**Example:**
+```typescript
+import { interceptRequest } from "@mcp-abap-adt/proxy/router/requestInterceptor";
+
+const intercepted = interceptRequest(req, body);
+console.log(intercepted.routingDecision.strategy);
+```
+
+## Proxy Modules
+
+### BTP Proxy
+
+#### `BtpProxy`
+
+A facade over the destination's credential. It does not carry requests — that is
+`forwardRequest()` below.
+
+##### `getAuthorizationHeader(destination): Promise<string | null>`
+
+The `Authorization` header VALUE for a destination — `Bearer <token>`, complete —
+or `null` where the credential is not a header at all.
+
+Asked on every request, deliberately. The credential renews behind this call, so
+a cache on the caller's side would serve the stale token and hide the renewal.
+
+##### `getTargetUrl(destination): Promise<string>`
+
+Where that destination's requests go: `targetUrl` from the config if set,
+otherwise `serviceUrl` from the service key. Throws when neither exists.
+
+##### `dispose(): void`
+
+Lets go of the credentials and brokers held. There are no timers to cancel.
+
+**Example:**
+```typescript
+import { createBtpProxy } from "@mcp-abap-adt/proxy/proxy/btpProxy";
+
+const proxy = await createBtpProxy(config);
+const authorization = await proxy.getAuthorizationHeader("my-destination");
+const targetUrl = await proxy.getTargetUrl("my-destination");
+```
+
+### Reverse Proxy
+
+#### `forwardRequest(clientReq, clientRes, targetBaseUrl, authorization, defaultHeaders?, requestBody?)`
+
+The single transparent pipe. Every transport goes through it.
+
+**Parameters:**
+- `clientReq` / `clientRes`: the incoming request and its response
+- `targetBaseUrl`: where to forward
+- `authorization`: a complete header VALUE, or `null` for no header at all. It is
+  NOT a token — composing `Bearer` around it would send `Bearer Bearer <token>`
+- `defaultHeaders`: injected first; client headers win
+- `requestBody`: for a caller that has already read the request. The SSE path
+  parses the JSON-RPC body because its error envelopes echo the `id`, and a
+  stream read once cannot be piped. Pass the bytes as they arrived, not a
+  re-serialised parse — the client's `content-length` is forwarded unchanged
+
+The response streams; nothing is buffered on the way back.
+
+
+## Error Handling
+
+### ~~`CircuitBreaker`~~ — removed in 4.0.0
+
+It guarded the buffered axios forward this release deletes. The forwarding path
+now streams, and a breaker there would mean buffering the response again — the
+thing being fixed. `circuitBreakerThreshold` and `circuitBreakerTimeout` are
+still accepted in configuration so existing files load unchanged, and have no
+effect.
+
+### ~~`ProxyRequest`~~ / ~~`ProxyResponse`~~ — removed in 4.0.0
+
+These described the JSON-RPC envelope the deleted axios path rebuilt by hand and
+answered with. Every transport now forwards through `forwardRequest()`, which
+carries the request and the response as they are, so there is no envelope for
+this package to name.