@mcp-abap-adt/core 4.5.2 → 4.6.0

package/docs/superpowers/plans/2026-03-31-https-server-support.md

@@ -0,0 +1,771 @@
+# HTTPS Server Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add TLS/HTTPS support to MCP server transports (HTTP and SSE) so clients can connect securely with a provided certificate.
+
+**Architecture:** Protocol is determined automatically by the presence of `tls.cert` + `tls.key` options. TLS config is per-transport (http/sse sections) to allow mixed setups. In standalone mode, `https.createServer(tlsOpts, app)` replaces `app.listen()`. Embedded mode ignores TLS (external app's responsibility).
+
+**Tech Stack:** Node.js `node:https`, `node:fs`, Express 5, existing YAML config + CLI argument infrastructure.
+
+---
+
+## File Map
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `src/lib/config/IServerConfig.ts` | Modify | Add `TlsConfig` interface and tls fields |
+| `src/lib/config/ArgumentsParser.ts` | Modify | Parse `--tls-cert`, `--tls-key`, `--tls-ca` CLI args + env vars |
+| `src/lib/config/yamlConfig.ts` | Modify | Add `tls` section to `YamlConfig`, validation, template, apply-to-args |
+| `src/lib/config/ServerConfigManager.ts` | Modify | Wire TLS fields from parsed args to `IServerConfig` |
+| `src/server/tlsUtils.ts` | Create | `createServerListener()` helper — shared by both transports |
+| `src/server/StreamableHttpServer.ts` | Modify | Use `createServerListener()` in `start()`, update log protocol |
+| `src/server/SseServer.ts` | Modify | Use `createServerListener()` in `start()`, update log protocol |
+| `src/server/launcher.ts` | Modify | Pass TLS config to server constructors, update help text |
+| `src/__tests__/unit/tlsServer.test.ts` | Create | Unit tests for TLS server creation |
+
+---
+
+### Task 1: Add TlsConfig to IServerConfig
+
+**Files:**
+- Modify: `src/lib/config/IServerConfig.ts`
+
+- [ ] **Step 1: Add TlsConfig interface and fields**
+
+In `src/lib/config/IServerConfig.ts`, add:
+
+```typescript
+/** TLS configuration for HTTPS server */
+export interface TlsConfig {
+  /** Path to TLS certificate file (PEM) */
+  cert: string;
+  /** Path to TLS private key file (PEM) */
+  key: string;
+  /** Path to CA certificate file (PEM), optional */
+  ca?: string;
+}
+```
+
+Add to `IServerConfig` in the `HTTP/SSE SPECIFIC` section:
+
+```typescript
+  /** TLS configuration for HTTPS (cert + key enables HTTPS automatically) */
+  tls?: TlsConfig;
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/lib/config/IServerConfig.ts
+git commit -m "feat: add TlsConfig interface to IServerConfig"
+```
+
+---
+
+### Task 2: Parse TLS CLI arguments
+
+**Files:**
+- Modify: `src/lib/config/ArgumentsParser.ts`
+
+- [ ] **Step 1: Add TLS fields to ParsedArguments**
+
+Add to `ParsedArguments` interface:
+
+```typescript
+  /** TLS certificate file path */
+  tlsCert?: string;
+  /** TLS private key file path */
+  tlsKey?: string;
+  /** TLS CA certificate file path */
+  tlsCa?: string;
+```
+
+- [ ] **Step 2: Add TLS parsing logic**
+
+In `ArgumentsParser.parse()`, after the SSE options block (after line ~257), add:
+
+```typescript
+    // Parse TLS options
+    result.tlsCert = getArgValue('--tls-cert') || process.env.MCP_TLS_CERT;
+    result.tlsKey = getArgValue('--tls-key') || process.env.MCP_TLS_KEY;
+    result.tlsCa = getArgValue('--tls-ca') || process.env.MCP_TLS_CA;
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/lib/config/ArgumentsParser.ts
+git commit -m "feat: parse --tls-cert, --tls-key, --tls-ca CLI args"
+```
+
+---
+
+### Task 3: Add TLS to YAML config
+
+**Files:**
+- Modify: `src/lib/config/yamlConfig.ts`
+
+- [ ] **Step 1: Add tls to YamlConfig interface**
+
+Add `tls` section inside both `http` and `sse` objects in `YamlConfig`:
+
+```typescript
+export interface YamlConfig {
+  // ... existing fields ...
+  http?: {
+    // ... existing fields ...
+    tls?: {
+      cert?: string;
+      key?: string;
+      ca?: string;
+    };
+  };
+  sse?: {
+    // ... existing fields ...
+    tls?: {
+      cert?: string;
+      key?: string;
+      ca?: string;
+    };
+  };
+}
+```
+
+- [ ] **Step 2: Add TLS validation to validateYamlConfig**
+
+After existing SSE validation (before the `return` statement), add:
+
+```typescript
+  // Validate TLS configuration (http)
+  if (config.http?.tls) {
+    const tls = config.http.tls;
+    if (tls.cert && !tls.key) {
+      errors.push('HTTP TLS: cert requires key to be specified');
+    }
+    if (tls.key && !tls.cert) {
+      errors.push('HTTP TLS: key requires cert to be specified');
+    }
+  }
+
+  // Validate TLS configuration (sse)
+  if (config.sse?.tls) {
+    const tls = config.sse.tls;
+    if (tls.cert && !tls.key) {
+      errors.push('SSE TLS: cert requires key to be specified');
+    }
+    if (tls.key && !tls.cert) {
+      errors.push('SSE TLS: key requires cert to be specified');
+    }
+  }
+```
+
+- [ ] **Step 3: Add TLS to applyYamlConfigToArgs**
+
+Inside the `// Apply HTTP options` block, add:
+
+```typescript
+    if (config.http.tls?.cert && !hasArg('--tls-cert')) {
+      addArg('--tls-cert', config.http.tls.cert);
+    }
+    if (config.http.tls?.key && !hasArg('--tls-key')) {
+      addArg('--tls-key', config.http.tls.key);
+    }
+    if (config.http.tls?.ca && !hasArg('--tls-ca')) {
+      addArg('--tls-ca', config.http.tls.ca);
+    }
+```
+
+Also inside the `// Apply SSE options` block, add the same (SSE YAML tls applies to same CLI args — both transports share the same tls cert/key/ca since only one transport runs at a time):
+
+```typescript
+    if (config.sse.tls?.cert && !hasArg('--tls-cert')) {
+      addArg('--tls-cert', config.sse.tls.cert);
+    }
+    if (config.sse.tls?.key && !hasArg('--tls-key')) {
+      addArg('--tls-key', config.sse.tls.key);
+    }
+    if (config.sse.tls?.ca && !hasArg('--tls-ca')) {
+      addArg('--tls-ca', config.sse.tls.ca);
+    }
+```
+
+- [ ] **Step 4: Add TLS to YAML template**
+
+In `generateYamlConfigTemplate()`, add to both `http:` and `sse:` sections:
+
+```yaml
+  # TLS configuration for HTTPS (both cert and key required)
+  # When configured, server starts in HTTPS mode automatically
+  # Note: only the active transport's TLS config is used
+  # tls:
+  #   cert: /path/to/server.crt
+  #   key: /path/to/server.key
+  #   ca: /path/to/ca.crt  # optional, for custom CA
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/config/yamlConfig.ts
+git commit -m "feat: add TLS section to YAML config with validation"
+```
+
+---
+
+### Task 4: Wire TLS config through ServerConfigManager
+
+**Files:**
+- Modify: `src/lib/config/ServerConfigManager.ts`
+
+- [ ] **Step 1: Add TLS to parseCommandLine**
+
+In `parseCommandLine()`, after the existing fields in the return object, add:
+
+```typescript
+      tls:
+        parsed.tlsCert && parsed.tlsKey
+          ? {
+              cert: parsed.tlsCert,
+              key: parsed.tlsKey,
+              ca: parsed.tlsCa,
+            }
+          : undefined,
+```
+
+- [ ] **Step 2: Add TLS to help text**
+
+In `generateHelp()`, add a TLS section to the OPTIONS area. In the help string, after `HTTP OPTIONS:` section, add:
+
+```
+TLS/HTTPS:
+  --tls-cert=<path>                Path to TLS certificate file (PEM)
+  --tls-key=<path>                 Path to TLS private key file (PEM)
+  --tls-ca=<path>                  Path to CA certificate file (PEM, optional)
+                                   When cert and key are provided, server starts in HTTPS mode
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/lib/config/ServerConfigManager.ts
+git commit -m "feat: wire TLS config from parsed args to IServerConfig"
+```
+
+---
+
+### Task 5: Create TLS server helper
+
+**Files:**
+- Create: `src/server/tlsUtils.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/__tests__/unit/tlsServer.test.ts`:
+
+```typescript
+import * as fs from 'node:fs';
+import * as https from 'node:https';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { createSelfSignedCert } from './helpers/selfSignedCert';
+import { createServerListener, getProtocol } from '../../server/tlsUtils';
+
+let certDir: string;
+let certPath: string;
+let keyPath: string;
+
+beforeAll(() => {
+  const { cert, key, dir } = createSelfSignedCert();
+  certDir = dir;
+  certPath = cert;
+  keyPath = key;
+});
+
+afterAll(() => {
+  fs.rmSync(certDir, { recursive: true, force: true });
+});
+
+describe('createServerListener', () => {
+  it('creates HTTPS server when tls config is provided', async () => {
+    const app = express();
+    app.get('/test', (_req, res) => res.json({ ok: true }));
+
+    const server = createServerListener(app, {
+      cert: certPath,
+      key: keyPath,
+    });
+
+    await new Promise<void>((resolve) => {
+      server.listen(0, '127.0.0.1', () => resolve());
+    });
+
+    const { port } = server.address() as AddressInfo;
+
+    // Use node:https to make request with rejectUnauthorized: false
+    const body = await new Promise<string>((resolve, reject) => {
+      https.get(
+        `https://127.0.0.1:${port}/test`,
+        { rejectUnauthorized: false },
+        (res) => {
+          let data = '';
+          res.on('data', (chunk) => (data += chunk));
+          res.on('end', () => resolve(data));
+        },
+      ).on('error', reject);
+    });
+
+    expect(JSON.parse(body)).toEqual({ ok: true });
+
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it('creates HTTP server when no tls config is provided', async () => {
+    const app = express();
+    app.get('/test', (_req, res) => res.json({ ok: true }));
+
+    const server = createServerListener(app);
+
+    await new Promise<void>((resolve) => {
+      server.listen(0, '127.0.0.1', () => resolve());
+    });
+
+    const { port } = server.address() as AddressInfo;
+    const res = await fetch(`http://127.0.0.1:${port}/test`);
+    expect(res.status).toBe(200);
+
+    const json = await res.json();
+    expect(json.ok).toBe(true);
+
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it('throws when cert file does not exist', () => {
+    const app = express();
+    expect(() =>
+      createServerListener(app, {
+        cert: '/nonexistent/cert.pem',
+        key: keyPath,
+      }),
+    ).toThrow(/cert/i);
+  });
+
+  it('throws when key file does not exist', () => {
+    const app = express();
+    expect(() =>
+      createServerListener(app, {
+        cert: certPath,
+        key: '/nonexistent/key.pem',
+      }),
+    ).toThrow(/key/i);
+  });
+});
+
+describe('getProtocol', () => {
+  it('returns https when tls config provided', () => {
+    expect(getProtocol({ cert: 'a', key: 'b' })).toBe('https');
+  });
+
+  it('returns http when no tls config', () => {
+    expect(getProtocol()).toBe('http');
+    expect(getProtocol(undefined)).toBe('http');
+  });
+});
+```
+
+Create `src/__tests__/unit/helpers/selfSignedCert.ts`:
+
+```typescript
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/**
+ * Generate a self-signed certificate for testing purposes.
+ * Uses openssl CLI (available on Linux/macOS).
+ */
+export function createSelfSignedCert(): {
+  cert: string;
+  key: string;
+  dir: string;
+} {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-tls-test-'));
+  const certPath = path.join(dir, 'server.crt');
+  const keyPath = path.join(dir, 'server.key');
+
+  execSync(
+    `openssl req -x509 -newkey rsa:2048 -keyout "${keyPath}" -out "${certPath}" -days 1 -nodes -subj "/CN=localhost"`,
+    { stdio: 'pipe' },
+  );
+
+  return { cert: certPath, key: keyPath, dir };
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx jest src/__tests__/unit/tlsServer.test.ts --no-coverage`
+Expected: FAIL — `createServerListener` module not found
+
+- [ ] **Step 3: Implement createServerListener**
+
+Create `src/server/tlsUtils.ts`:
+
+```typescript
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import type { TlsConfig } from '../lib/config/IServerConfig.js';
+
+/**
+ * Create HTTP or HTTPS server based on TLS configuration.
+ *
+ * When `tls` is provided with cert + key paths, creates an HTTPS server.
+ * Otherwise creates a plain HTTP server.
+ *
+ * @param app - Express application (or any http.RequestListener)
+ * @param tls - Optional TLS configuration with file paths
+ * @returns http.Server or https.Server
+ */
+export function createServerListener(
+  app: http.RequestListener,
+  tls?: TlsConfig,
+): http.Server | https.Server {
+  if (!tls) {
+    return http.createServer(app);
+  }
+
+  if (!fs.existsSync(tls.cert)) {
+    throw new Error(`TLS cert file not found: ${tls.cert}`);
+  }
+  if (!fs.existsSync(tls.key)) {
+    throw new Error(`TLS key file not found: ${tls.key}`);
+  }
+  if (tls.ca && !fs.existsSync(tls.ca)) {
+    throw new Error(`TLS CA file not found: ${tls.ca}`);
+  }
+
+  const tlsOptions: https.ServerOptions = {
+    cert: fs.readFileSync(tls.cert),
+    key: fs.readFileSync(tls.key),
+    ...(tls.ca && { ca: fs.readFileSync(tls.ca) }),
+  };
+
+  return https.createServer(tlsOptions, app);
+}
+
+/**
+ * Returns the protocol string based on TLS configuration.
+ */
+export function getProtocol(tls?: TlsConfig): 'https' | 'http' {
+  return tls ? 'https' : 'http';
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx jest src/__tests__/unit/tlsServer.test.ts --no-coverage`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/server/tlsUtils.ts src/__tests__/unit/tlsServer.test.ts src/__tests__/unit/helpers/selfSignedCert.ts
+git commit -m "feat: add createServerListener TLS helper with tests"
+```
+
+---
+
+### Task 6: Integrate TLS into StreamableHttpServer
+
+**Files:**
+- Modify: `src/server/StreamableHttpServer.ts`
+
+- [ ] **Step 1: Add TLS to options and constructor**
+
+Add/update imports at the top:
+
+```typescript
+import type { Server as HttpServer } from 'node:http';
+import type { Server as HttpsServer } from 'node:https';
+import type { TlsConfig } from '../lib/config/IServerConfig.js';
+import { createServerListener, getProtocol } from './tlsUtils.js';
+```
+
+Add to `StreamableHttpServerOptions`:
+
+```typescript
+  /**
+   * TLS configuration for HTTPS mode
+   * When cert + key are provided, server starts in HTTPS mode
+   */
+  tls?: TlsConfig;
+```
+
+Update `standaloneServer` type in the class (line 74):
+
+```typescript
+private standaloneServer?: HttpServer | HttpsServer;
+```
+
+Add field to the class and set it in constructor:
+
+```typescript
+private readonly tls?: TlsConfig;
+// In constructor:
+this.tls = opts?.tls;
+```
+
+- [ ] **Step 2: Update start() method**
+
+Replace in `start()`:
+
+```typescript
+// OLD:
+const server = app.listen(this.port, this.host);
+this.standaloneServer = server;
+
+server.once('listening', () => {
+  console.error(
+    `[StreamableHttpServer] Server started on ${this.host}:${this.port}`,
+  );
+  console.error(
+    `[StreamableHttpServer] Endpoint: http://${this.host}:${this.port}${this.path}`,
+  );
+  resolve();
+});
+```
+
+With:
+
+```typescript
+const protocol = getProtocol(this.tls);
+const server = createServerListener(app as any, this.tls);
+this.standaloneServer = server;
+
+server.listen(this.port, this.host);
+server.once('listening', () => {
+  console.error(
+    `[StreamableHttpServer] Server started on ${this.host}:${this.port}`,
+  );
+  console.error(
+    `[StreamableHttpServer] Endpoint: ${protocol}://${this.host}:${this.port}${this.path}`,
+  );
+  resolve();
+});
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/server/StreamableHttpServer.ts
+git commit -m "feat: integrate TLS into StreamableHttpServer"
+```
+
+---
+
+### Task 7: Integrate TLS into SseServer
+
+**Files:**
+- Modify: `src/server/SseServer.ts`
+
+- [ ] **Step 1: Add TLS to options and constructor**
+
+Add/update imports at the top:
+
+```typescript
+import type { Server as HttpServer } from 'node:http';
+import type { Server as HttpsServer } from 'node:https';
+import type { TlsConfig } from '../lib/config/IServerConfig.js';
+import { createServerListener, getProtocol } from './tlsUtils.js';
+```
+
+Add to `SseServerOptions`:
+
+```typescript
+  /**
+   * TLS configuration for HTTPS mode
+   */
+  tls?: TlsConfig;
+```
+
+Update `standaloneServer` type in the class (line 79):
+
+```typescript
+private standaloneServer?: HttpServer | HttpsServer;
+```
+
+Add field and set in constructor:
+
+```typescript
+private readonly tls?: TlsConfig;
+// In constructor:
+this.tls = opts?.tls;
+```
+
+- [ ] **Step 2: Update start() method**
+
+Replace in `start()`:
+
+```typescript
+// OLD:
+const server = app.listen(this.port, this.host);
+this.standaloneServer = server;
+
+server.once('listening', () => {
+  console.error(
+    `[SseServer] Server started on ${this.host}:${this.port}`,
+  );
+  console.error(
+    `[SseServer] SSE endpoint: http://${this.host}:${this.port}${this.ssePath}`,
+  );
+  console.error(
+    `[SseServer] POST endpoint: http://${this.host}:${this.port}${this.postPath}`,
+  );
+  resolve();
+});
+```
+
+With:
+
+```typescript
+const protocol = getProtocol(this.tls);
+const server = createServerListener(app as any, this.tls);
+this.standaloneServer = server;
+
+server.listen(this.port, this.host);
+server.once('listening', () => {
+  console.error(
+    `[SseServer] Server started on ${this.host}:${this.port}`,
+  );
+  console.error(
+    `[SseServer] SSE endpoint: ${protocol}://${this.host}:${this.port}${this.ssePath}`,
+  );
+  console.error(
+    `[SseServer] POST endpoint: ${protocol}://${this.host}:${this.port}${this.postPath}`,
+  );
+  resolve();
+});
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/server/SseServer.ts
+git commit -m "feat: integrate TLS into SseServer"
+```
+
+---
+
+### Task 8: Pass TLS config from launcher
+
+**Files:**
+- Modify: `src/server/launcher.ts`
+
+- [ ] **Step 1: Pass tls to SseServer constructor**
+
+In `launcher.ts`, find the SseServer creation block (~line 335) and add `tls`:
+
+```typescript
+const server = new SseServer(handlersRegistry, authBrokerFactory, {
+  host: config.host,
+  port: config.port,
+  ssePath: config.ssePath,
+  postPath: config.postPath,
+  defaultDestination:
+    config.mcpDestination ?? (config.envFile ? 'default' : undefined),
+  logger: loggerForTransport,
+  tls: config.tls,  // <-- add this
+});
+```
+
+- [ ] **Step 2: Pass tls to StreamableHttpServer constructor**
+
+Find the StreamableHttpServer creation block (~line 350) and add `tls`:
+
+```typescript
+const server = new StreamableHttpServer(handlersRegistry, authBrokerFactory, {
+  host: config.host,
+  port: config.port,
+  enableJsonResponse: config.httpJsonResponse,
+  path: config.httpPath,
+  defaultDestination:
+    config.mcpDestination ?? (config.envFile ? 'default' : undefined),
+  logger: loggerForTransport,
+  tls: config.tls,  // <-- add this
+});
+```
+
+- [ ] **Step 3: Add TLS env vars to V2_HELP_SECTIONS**
+
+In `V2_HELP_SECTIONS`, add to the `MCP Server Configuration:` block:
+
+```
+    MCP_TLS_CERT                   Path to TLS certificate file (PEM)
+    MCP_TLS_KEY                    Path to TLS private key file (PEM)
+    MCP_TLS_CA                     Path to TLS CA certificate file (PEM, optional)
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/server/launcher.ts
+git commit -m "feat: pass TLS config from launcher to HTTP/SSE servers"
+```
+
+---
+
+### Task 9: Build and verify
+
+- [ ] **Step 1: Run build**
+
+Run: `npm run build`
+Expected: No compilation errors
+
+- [ ] **Step 2: Run existing unit tests**
+
+Run: `npx jest src/__tests__/unit/ --no-coverage`
+Expected: All pass (including new TLS tests and existing health endpoint tests)
+
+- [ ] **Step 3: Run linter**
+
+Run: `npm run lint`
+Expected: No errors
+
+- [ ] **Step 4: Commit any fixes if needed**
+
+---
+
+## Usage Examples (for documentation reference)
+
+```bash
+# CLI with TLS
+mcp-abap-adt --transport=http --port=8443 \
+  --tls-cert=/path/to/server.crt \
+  --tls-key=/path/to/server.key
+
+# CLI with CA chain
+mcp-abap-adt --transport=http --port=8443 \
+  --tls-cert=/path/to/server.crt \
+  --tls-key=/path/to/server.key \
+  --tls-ca=/path/to/ca-chain.crt
+
+# Via environment variables
+MCP_TRANSPORT=http MCP_HTTP_PORT=8443 \
+  MCP_TLS_CERT=/path/to/server.crt \
+  MCP_TLS_KEY=/path/to/server.key \
+  mcp-abap-adt
+```
+
+```yaml
+# YAML config
+transport: http
+http:
+  port: 8443
+  host: 0.0.0.0
+  tls:
+    cert: /path/to/server.crt
+    key: /path/to/server.key
+    ca: /path/to/ca-chain.crt
+```