sap-ai-dev-toolkit 0.7.9 → 0.8.1

package/README.md

@@ -272,8 +272,35 @@ The installer handles VSP provisioning automatically:
 
 Setup detects where it is running. With `H2O_URL` set, it treats the environment as SAP Business Application Studio and opens a checkbox picker for BAS destinations, with no destinations selected by default. Use **Space** to choose destinations and **Enter** to confirm. Press **a** to toggle all destinations (select all if any are unchecked; otherwise clear the selection). Confirming with none selected removes this add-on's managed MCP entries. When the `cf` CLI 8.18 or newer is authenticated to a targeted space, setup first offers an optional import from that space's Destination service; type **y** then **Enter** to include it, or press **Enter** to skip. Accepted CF and BAS destinations appear together in the picker.
 
-Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint, so setup asks you to confirm the ADT URL for each selected system. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup can instead write an experimental `SAP_AUTH_MODE=windows-sso` entry without username/password prompts; this requires the ADT endpoint to support HTTP Negotiate/SPNEGO. Runtime uses the bundled Windows Negotiate helper by default, or a trusted custom helper configured with `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER`. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config.
+Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup can instead write an experimental `SAP_AUTH_MODE=windows-sso` entry without username/password prompts; this requires the ADT endpoint to support HTTP Negotiate/SPNEGO. Runtime uses the bundled Windows Negotiate helper by default, or a trusted custom helper configured with `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER`. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config.
 
+### 🖥️ Local machine SAP GUI support
+
+Local setup is intended for developers running the MCP server from their own workstation rather than SAP Business Application Studio.
+
+Supported discovery and runtime behavior:
+
+- **Discovery sources:** SAP GUI landscape XML and `saplogon.ini` style configuration on macOS and Windows. Setup de-duplicates entries, ignores incomplete DIAG records, and shows the discovered SAP systems in the same checkbox picker used for BAS destinations.
+- **Client selection:** SAP GUI entries may contain one default client but cannot reliably list every ABAP client available through ADT. Setup asks for one or more 3-digit clients per selected system; enter comma-separated values such as `100,200` to create separate MCP servers for each client.
+- **ADT endpoint derivation:** SAP GUI entries usually contain DIAG/router information, not the HTTP(S) ADT endpoint. Setup derives the common ADT port from the SAP instance when possible, for example instance `00` → `https://host:44300`, and asks for confirmation only when configuring the selected entry.
+- **Credential handling:** username/password local entries use VS Code MCP input prompts (`${input:...}`) at server start. Plain SAP credentials are not written to `mcp.json`.
+- **Windows SSO:** local Windows entries can use `SAP_AUTH_MODE=windows-sso` instead of username/password prompts when the ABAP ADT endpoint supports HTTP Negotiate/SPNEGO. The runtime starts a loopback ADT proxy and uses the bundled Windows SSPI helper unless `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER` points to a trusted custom helper. NTLM fallback is rejected.
+- **IP-address HTTPS self-healing:** if the confirmed ADT URL is `https://<ip>:<port>` and the certificate is issued to DNS names, setup reads the certificate DNS SANs automatically and stores them as `SAP_TLS_SERVER_NAMES`. At runtime a loopback proxy dials the IP address but verifies TLS against those discovered DNS names, trying them one by one. Certificate verification stays enabled; there is no `--insecure` mode.
+- **Private CAs:** if the SAP HTTPS certificate chains to an internal CA that is not trusted by the local Node runtime, set `SAP_TLS_CA_FILE` or `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` to a PEM CA bundle. This adds trust roots for the self-healing proxy without disabling certificate validation.
+- **Redirect and request safety:** local loopback proxies reject cross-origin forward-form requests and rewrite same-origin SAP redirects back through the loopback listener, so VSP stays on the safe route.
+
+Typical local setup flow:
+
+```sh
+sap-ai-dev --setup
+```
+
+1. Select the discovered SAP GUI system with **Space** and confirm with **Enter**.
+2. Confirm the detected/default SAP client, or enter multiple clients such as `100,200`.
+3. Accept the proposed ADT URL when it is correct, or edit it if your landscape exposes ADT through a different HTTP(S) host/port.
+4. If setup discovers certificate DNS names for an IP-based HTTPS URL, accept the yes/no TLS self-healing prompt.
+5. Choose password or Windows SSO when the prompt is available.
+6. Start each generated MCP server from VS Code's **MCP: List Servers** command.
 
 The same postinstall offers the bundled agents and skills for several AI coding harnesses in a checkbox picker. **GitHub Copilot** and **Claude Code** start pre-checked, so pressing **Enter** alone installs both; **Space** selects or deselects a harness, **a** toggles all seven, and confirming with none selected skips the step without changing files. When destination MCP setup succeeds, the generated managed MCP servers are also mirrored into selected harnesses that have a stable user-level JSON MCP configuration (Claude Code, Cursor, Gemini CLI, and Pi Coding Agent). GitHub Copilot continues to use the BAS/VS Code MCP configuration written during destination setup. With no interactive terminal, the assets are installed for GitHub Copilot only; set `SAP_AI_DEV_TOOLKIT_HARNESSES` to a comma-separated list of harness ids (`github-copilot`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `opencode`, `pi-coding-agent`) to choose non-interactively.
 
@@ -750,6 +777,9 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 | `SAP_AI_DEV_TOOLKIT_MODE` | VSP child mode (`expert` by default; `focused` omits `ActivateMultiple`, `GetUserTransports`, and `GetTransportInfo`). The proxy exposes its curated tool subset and local workflow tools, including `LintABAP`. |
 | `SAP_ALLOW_TRANSPORTABLE_EDITS` | Generated MCP entries set this to `true` to permit source edits in transportable packages; VSP safety checks and SAP authorizations still apply. |
 | `SAP_AUTH_MODE=windows-sso` | Local SAP GUI entry mode for experimental Windows Integrated Authentication. Runtime starts a loopback ADT proxy and does not pass SAP username/password credentials to VSP. |
+| `SAP_TLS_SERVER_NAMES` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES` | Comma-separated local SAP GUI TLS self-healing names, normally auto-discovered during setup from the SAP HTTPS certificate when `SAP_URL` uses an IP address. Runtime tries them one by one while keeping certificate validation enabled. |
+| `SAP_TLS_SERVER_NAME` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME` | Single-name compatibility form of the local SAP GUI TLS self-healing override. Prefer the auto-discovered plural variable written by setup. |
+| `SAP_TLS_CA_FILE` / `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` | Optional PEM CA bundle for the local TLS self-healing proxy when the SAP HTTPS certificate chains to a private CA that is not in the OS/Node trust store. Certificate verification remains enabled. |
 | `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER` / `SAP_AI_DEV_TOOLKIT_SSPI_HELPER` | Optional trusted Windows helper executable used by the local Windows SSO proxy to convert an HTTP `WWW-Authenticate: Negotiate` challenge into a Kerberos/SPNEGO token. NTLM fallback is rejected because it is connection-oriented and unsafe for this proxy shape. When unset on Windows, the bundled PowerShell SSPI helper is used. A custom helper receives one JSON line on stdin (`url`, `challenge`, `mechanism`) and prints the base64 token on stdout. |
 | `SAP_AI_DEV_TOOLKIT_HTTP_PROXY` | Egress proxy for BAS discovery and probe traffic. Takes precedence over `HTTP_PROXY`/`http_proxy`; unset means the default BAS proxy for `.dest` hosts, empty means direct. |
 | `SAP_AI_DEV_TOOLKIT_REQUEST_TIMEOUT_MS` | Per-request timeout for calls forwarded to a VSP child (default 600000 = 10 minutes; `0` disables). A stalled request fails with a timeout error; the child is left running. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.7.9",
+  "version": "0.8.1",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",

package/src/launcher.mjs

@@ -11,6 +11,7 @@ import { installMcpConfig, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createWindowsSsoAdtProxy } from './windows-sso-adt-proxy.mjs';
+import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
 import { withBrandedEnvironment } from './branding.mjs';
 import { redactText } from './redact.mjs';
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -175,8 +176,18 @@ async function configuredLocalSapGuiDestination(env) {
   const name = env.SAP_AI_DEV_TOOLKIT_DESTINATION || env.SAP_SYSTEM_ID || 'local-sap';
   if (!env.SAP_URL) throw new Error('SAP_URL is required for local SAP GUI MCP entries. Rerun sap-ai-dev --setup and enter the ADT URL.');
   const authMode = String(env.SAP_AUTH_MODE || '').toLowerCase();
+  const tlsServerName = String(env.SAP_TLS_SERVER_NAME || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME || '').trim();
+  const tlsServerNames = String(env.SAP_TLS_SERVER_NAMES || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES || tlsServerName).split(',').map(value => value.trim()).filter(Boolean);
+  const tlsCaFile = String(env.SAP_TLS_CA_FILE || env.SAP_AI_DEV_TOOLKIT_TLS_CA_FILE || '').trim();
+  const tlsRoute = tlsServerNames.length
+    ? await createTlsServerNameAdtProxy({ destinationUrl: env.SAP_URL, tlsServerNames, caFile: tlsCaFile || undefined })
+    : null;
+  const adtUrl = tlsRoute?.url || env.SAP_URL;
+  const closeRoute = async route => {
+    await Promise.all([route?.close?.(), tlsRoute?.close?.()].filter(Boolean).map(close => Promise.resolve().then(close).catch(() => {})));
+  };
   if (authMode === 'windows-sso') {
-    const route = await createWindowsSsoAdtProxy({ destinationUrl: env.SAP_URL, env });
+    const route = await createWindowsSsoAdtProxy({ destinationUrl: adtUrl, env });
     return {
       source: 'sap-gui-local',
       name,
@@ -185,21 +196,23 @@ async function configuredLocalSapGuiDestination(env) {
       client: env.SAP_CLIENT || '001',
       authentication: 'WindowsSSO',
       childEnv: {},
-      close: route.close,
-      probe: { status: 'configured', available: true }
+      close: () => closeRoute(route),
+      probe: { status: tlsRoute ? 'configured-tls-server-name' : 'configured', available: true }
     };
   }
   return {
     source: 'sap-gui-local',
     name,
-    url: env.SAP_URL,
+    url: adtUrl,
+    backendUrl: tlsRoute ? env.SAP_URL : undefined,
     client: env.SAP_CLIENT || '001',
     authentication: 'Basic',
     childEnv: {
       SAP_USER: env.SAP_USER || env.SAP_USERNAME || '',
       SAP_PASSWORD: env.SAP_PASSWORD || env.SAP_PASS || ''
     },
-    probe: { status: 'configured', available: true }
+    close: tlsRoute?.close,
+    probe: { status: tlsRoute ? 'configured-tls-server-name' : 'configured', available: true }
   };
 }
 

package/src/mcp-config.mjs

@@ -192,6 +192,8 @@ export function buildMcpEntries(destinations, env = process.env) {
         SAP_URL: String(destination.url),
         SAP_CLIENT: String(destination.client || '001'),
         ...(destination.systemId ? { SAP_SYSTEM_ID: String(destination.systemId) } : {}),
+        ...(Array.isArray(destination.tlsServerNames) && destination.tlsServerNames.length ? { SAP_TLS_SERVER_NAMES: destination.tlsServerNames.join(',') } : {}),
+        ...(!Array.isArray(destination.tlsServerNames) && destination.tlsServerName ? { SAP_TLS_SERVER_NAME: String(destination.tlsServerName) } : {}),
         ...(destination.childEnv || {})
       });
     } else {

package/src/setup.mjs

@@ -1,11 +1,13 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { platform } from 'node:os';
+import { isIP } from 'node:net';
 import { checkboxPrompt, colorText, formatStatus, textPrompt } from './terminal-ui.mjs';
 import { discoverDestinations, remediation } from './bas-discovery.mjs';
 import { defaultAdtUrl, discoverSapGuiSystems } from './local-sap-gui.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys, findOrphanedCloudFoundryServiceKeys } from './cf-destination.mjs';
 import { SAP_DEVELOPMENT_MCP_SERVERS, collectCloudFoundryKeyReferencesFromAllEntries, collectManagedCloudFoundryKeyReferences, installMcpConfig, readMcpConfig, resolveMcpConfigPath } from './mcp-config.mjs';
+import { discoverCertificateDnsNames } from './tls-adt-proxy.mjs';
 
 const SETUP_COMMAND = 'sap-ai-dev --setup';
 
@@ -43,6 +45,51 @@ async function confirmCloudFoundryImport({ input = stdin, output = stdout } = {}
   }
 }
 
+export function parseSapClientList(value, fallback = '001') {
+  const supplied = String(value ?? '').trim();
+  const raw = supplied || String(fallback || '001').trim() || '001';
+  const clients = raw.split(',').map(client => client.trim()).filter(Boolean);
+  const unique = [];
+  const seen = new Set();
+  for (const client of clients) {
+    if (!/^\d{3}$/.test(client)) throw new Error('Enter one or more SAP clients as 3 digits, separated by commas, for example 100 or 100,200.');
+    if (!seen.has(client)) {
+      seen.add(client);
+      unique.push(client);
+    }
+  }
+  if (!unique.length) throw new Error('Enter at least one SAP client.');
+  return unique;
+}
+
+async function promptSapClients(destination, { input = stdin, output = stdout } = {}) {
+  const fallback = destination.client || '001';
+  const answer = await textPrompt({
+    message: `SAP client(s) for ${destination.name}`,
+    placeholder: fallback,
+    required: false,
+    validate: value => {
+      try { parseSapClientList(value, fallback); return true; }
+      catch (error) { return error.message; }
+    }
+  }, { input, output });
+  return parseSapClientList(answer, fallback);
+}
+
+function localSystemDiscriminator(destination) {
+  return [destination.systemId, destination.host, destination.instance].map(value => String(value || '').trim()).filter(Boolean).join(' ');
+}
+
+function localClientDestinationName(destination, client, { multipleClients = false, duplicateSystemName = false } = {}) {
+  const suffix = [];
+  if (multipleClients || duplicateSystemName) suffix.push(client);
+  if (duplicateSystemName) {
+    const discriminator = localSystemDiscriminator(destination);
+    if (discriminator) suffix.push(discriminator);
+  }
+  return suffix.length ? `${destination.name} ${suffix.join(' ')}` : destination.name;
+}
+
 
 function safeProbe(probe) {
   const result = {};
@@ -79,6 +126,8 @@ function safeLocalSapGuiDestination(destination) {
     authentication: destination.authentication || 'Basic',
     authMode: destination.authMode,
     proxyType: 'Internet',
+    tlsServerName: destination.tlsServerName,
+    tlsServerNames: destination.tlsServerNames,
     probe: safeProbe(destination.probe),
     childEnv: destination.childEnv || {}
   };
@@ -289,7 +338,7 @@ export async function runSetup({
   print(output, '  Space = select/deselect · a = toggle all · Enter = confirm.');
   print(output, '  Nothing selected removes this add-on’s MCP entries.');
   print(output, '');
-  const selected = await checkboxPrompt({
+  let selected = await checkboxPrompt({
     message: colorText('🧭 Select destinations', 'cyan', output),
     choices,
     required: false,
@@ -298,12 +347,23 @@ export async function runSetup({
 
   if (!isBas && selected.length) {
     print(output, '');
-    print(output, formatStatus('SAP GUI landscapes do not contain ADT HTTP(S) endpoints. Confirm the ADT URL and authentication for each selected system.', 'step', output, 'Local SAP GUI'));
+    print(output, formatStatus('SAP GUI landscapes do not contain ADT HTTP(S) endpoints or a complete client catalog. Confirm the SAP client(s), ADT URL, and authentication for each selected system.', 'step', output, 'Local SAP GUI'));
+    print(output, '  Enter multiple clients as comma-separated 3-digit values, for example 100,200. Setup creates one isolated MCP server per system/client pair.');
     if (windowsSsoSetupAvailable(env)) print(output, '  Windows SSO is experimental and only applies to ADT systems configured for HTTP Integrated Authentication. Username/password remains the default.');
+    const selectedNameCounts = selected.reduce((counts, destination) => {
+      const key = String(destination.name).toLowerCase();
+      counts.set(key, (counts.get(key) || 0) + 1);
+      return counts;
+    }, new Map());
+    const expanded = [];
     for (const destination of selected) {
+      const duplicateSystemName = (selectedNameCounts.get(String(destination.name).toLowerCase()) || 0) > 1;
+      const discriminator = duplicateSystemName ? localSystemDiscriminator(destination) : '';
+      const promptLabel = discriminator ? `${destination.name} (${discriminator})` : destination.name;
+      const clients = await promptSapClients({ ...destination, name: promptLabel }, { input, output });
       const fallback = defaultAdtUrl(destination);
       const url = await textPrompt({
-        message: `ADT URL for ${destination.name}`,
+        message: `ADT URL for ${promptLabel}`,
         placeholder: fallback || 'https://host:44300',
         validate: value => {
           const candidate = value || fallback;
@@ -320,26 +380,54 @@ export async function runSetup({
         required: false
       }, { input, output });
       destination.url = url || fallback;
-      const authMode = await chooseLocalAuthMode(destination, { input, output, env });
+      const parsedAdtUrl = new URL(destination.url);
+      if (parsedAdtUrl.protocol === 'https:' && isIP(parsedAdtUrl.hostname)) {
+        print(output, formatStatus('The ADT URL uses an IP address. Setup will inspect the SAP HTTPS certificate and can enable TLS self-healing automatically; certificate validation remains enabled.', 'warning', output, 'TLS self-heal'));
+        let discoveredNames = [];
+        try { discoveredNames = await discoverCertificateDnsNames(destination.url); }
+        catch { discoveredNames = []; }
+        if (discoveredNames.length) {
+          const preview = discoveredNames.slice(0, 5).join(', ');
+          const answer = await textPrompt({
+            message: `Use discovered certificate DNS name${discoveredNames.length === 1 ? '' : 's'} for ${promptLabel}: ${preview}${discoveredNames.length > 5 ? ', ...' : ''}? (y/Enter=yes, n=no)`,
+            placeholder: 'y',
+            required: false,
+            validate: value => /^(?:|y|yes|n|no)$/i.test(String(value || '').trim()) || 'Enter y or n.'
+          }, { input, output });
+          if (!/^n(?:o)?$/i.test(String(answer || '').trim())) {
+            destination.tlsServerNames = discoveredNames;
+            destination.tlsServerName = discoveredNames[0];
+          }
+        } else {
+          print(output, formatStatus('No DNS subjectAltName entries could be read from the SAP HTTPS certificate. TLS self-healing was not configured automatically.', 'warning', output, 'TLS self-heal'));
+        }
+      }
+      const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
       destination.authentication = authMode === 'windows-sso' ? 'WindowsSSO' : 'Basic';
       destination.authMode = authMode;
-      if (authMode === 'windows-sso') {
-        destination.childEnv = { SAP_AUTH_MODE: 'windows-sso' };
-        destination.inputs = [];
-      } else {
-        const userInputId = `sap-ai-dev-${destination.serverName || destination.name}-user`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
-        const passwordInputId = `sap-ai-dev-${destination.serverName || destination.name}-password`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
-        destination.childEnv = {
-          SAP_AUTH_MODE: 'basic',
-          SAP_USER: `\${input:${userInputId}}`,
-          SAP_PASSWORD: `\${input:${passwordInputId}}`
-        };
-        destination.inputs = [
-          { id: userInputId, type: 'promptString', description: `SAP user for ${destination.name}` },
-          { id: passwordInputId, type: 'promptString', description: `SAP password for ${destination.name}`, password: true }
-        ];
+      for (const client of clients) {
+        const name = localClientDestinationName(destination, client, { multipleClients: clients.length > 1, duplicateSystemName });
+        const localDestination = { ...destination, name, serverName: name, client };
+        if (authMode === 'windows-sso') {
+          localDestination.childEnv = { SAP_AUTH_MODE: 'windows-sso' };
+          localDestination.inputs = [];
+        } else {
+          const userInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-user`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+          const passwordInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-password`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+          localDestination.childEnv = {
+            SAP_AUTH_MODE: 'basic',
+            SAP_USER: `\${input:${userInputId}}`,
+            SAP_PASSWORD: `\${input:${passwordInputId}}`
+          };
+          localDestination.inputs = [
+            { id: userInputId, type: 'promptString', description: `SAP user for ${localDestination.name}` },
+            { id: passwordInputId, type: 'promptString', description: `SAP password for ${localDestination.name}`, password: true }
+          ];
+        }
+        expanded.push(localDestination);
       }
     }
+    selected = expanded;
   }
 
   let sapDevelopmentServers = [];

package/src/tls-adt-proxy.mjs

@@ -0,0 +1,122 @@
+import http from 'node:http';
+import https from 'node:https';
+import tls from 'node:tls';
+import { once } from 'node:events';
+import { readFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
+
+const HOP_BY_HOP = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailer', 'transfer-encoding', 'upgrade'
+]);
+
+function filteredHeaders(headers) {
+  const result = { ...headers };
+  for (const name of Object.keys(result)) {
+    if (HOP_BY_HOP.has(name.toLowerCase())) delete result[name];
+  }
+  return result;
+}
+
+function requestHeaders(headers, backend) {
+  return { ...filteredHeaders(headers), host: backend.host };
+}
+
+function parseSubjectAltName(value) {
+  return String(value || '')
+    .split(/,\s*/)
+    .map(item => item.match(/^DNS:(.+)$/i)?.[1]?.trim())
+    .filter(Boolean);
+}
+
+export async function discoverCertificateDnsNames(destinationUrl) {
+  const backend = new URL(destinationUrl);
+  if (backend.protocol !== 'https:') return [];
+  const socket = tls.connect({
+    host: backend.hostname,
+    port: Number(backend.port || 443),
+    ...(isIP(backend.hostname) ? {} : { servername: backend.hostname }),
+    rejectUnauthorized: false
+  });
+  try {
+    await once(socket, 'secureConnect');
+    const certificate = socket.getPeerCertificate();
+    return [...new Set(parseSubjectAltName(certificate?.subjectaltname))];
+  } finally {
+    socket.destroy();
+  }
+}
+
+function responseHeaders(headers, backend, clientReq) {
+  const result = filteredHeaders(headers);
+  const location = result.location;
+  if (typeof location === 'string') {
+    try {
+      const parsed = new URL(location, backend);
+      if (parsed.origin === backend.origin) {
+        result.location = `http://${clientReq.headers.host}${parsed.pathname}${parsed.search}${parsed.hash}`;
+      }
+    } catch {}
+  }
+  return result;
+}
+
+/**
+ * Starts a loopback HTTP reverse proxy for ADT HTTPS endpoints whose network
+ * address and certificate identity differ. The proxy dials the configured
+ * backend URL but verifies TLS with tlsServerName; CA validation stays enabled.
+ */
+export async function createTlsServerNameAdtProxy({ destinationUrl, tlsServerName, tlsServerNames, caFile } = {}) {
+  const backend = new URL(destinationUrl);
+  if (backend.protocol !== 'https:') throw new Error('TLS server-name override requires an https:// SAP URL.');
+  const serverNames = [...new Set([...(Array.isArray(tlsServerNames) ? tlsServerNames : []), ...String(tlsServerName || '').split(',')].map(value => String(value || '').trim()).filter(Boolean))];
+  if (!serverNames.length) throw new Error('TLS server-name override requires a DNS name.');
+
+  const ca = caFile ? await readFile(caFile) : undefined;
+  const server = http.createServer((clientReq, clientRes) => {
+    let target;
+    try {
+      target = new URL(clientReq.url || '/', backend);
+      if (target.origin !== backend.origin) throw new Error('cross-origin request rejected');
+    } catch (error) {
+      clientRes.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+      clientRes.end(`ADT TLS proxy rejected request: ${error.message}`);
+      return;
+    }
+    const chunks = [];
+    clientReq.on('data', chunk => chunks.push(chunk));
+    clientReq.on('end', () => {
+      const body = Buffer.concat(chunks);
+      const tryServerName = index => {
+        const request = https.request({
+          protocol: 'https:',
+          hostname: backend.hostname,
+          port: backend.port || 443,
+          method: clientReq.method,
+          path: `${target.pathname}${target.search}`,
+          headers: requestHeaders(clientReq.headers, backend),
+          servername: serverNames[index],
+          rejectUnauthorized: true,
+          ...(ca ? { ca } : {})
+        }, backendRes => {
+          clientRes.writeHead(backendRes.statusCode || 502, backendRes.statusMessage, responseHeaders(backendRes.headers, backend, clientReq));
+          backendRes.pipe(clientRes);
+        });
+        request.on('error', error => {
+          if (index + 1 < serverNames.length && /certificate|hostname|altname|x509/i.test(error.message)) return tryServerName(index + 1);
+          if (!clientRes.headersSent) clientRes.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+          clientRes.end(`ADT TLS proxy failed: ${error.message}`);
+        });
+        request.end(body);
+      };
+      tryServerName(0);
+    });
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const { port } = server.address();
+  return {
+    url: `http://127.0.0.1:${port}`,
+    close: () => new Promise(resolve => server.close(() => resolve()))
+  };
+}