@mcp-abap-adt/core 6.8.0 → 6.9.0

package/docs/superpowers/plans/innovations-from-sap-adt-mcp.md

@@ -0,0 +1,103 @@
+# План інновацій з аналізу `sap-adt-mcp`
+
+> Джерело: `~/prj/sap-adt-mcp` (окремий open-source MCP-сервер для SAP ADT, TS, MCP SDK v1.x).
+> Мета цього документа — зафіксувати, що з їхніх рішень варто перенести до нашого стеку,
+> у який саме компонент/пакет це лягає, який буст дає, і що ми дивимось «для довідки», але собі не робимо.
+>
+> Це **план-кошик ідей**, а не план імплементації. Рішення «що/де робити» приймаємо окремо по кожному пункту.
+
+## Контекст нашого стеку (важливо для оцінки вартості)
+
+На відміну від `sap-adt-mcp` (моноліт: один процес, один `.sap-profiles.json`, axios усередині),
+у нас функціонал розкладений по пакетах:
+
+- **mcp-abap-adt** — MCP-сервер (handlers, server transport, auth broker factory `src/lib/auth/`).
+- **mcp-abap-adt-clients** — ADT-клієнти (`AdtClient`, `AdtClientLegacy`, executors, core).
+- **пакет-конектор** — нижній шар з'єднання/сесії.
+- (+ типи/спільні утиліти).
+
+**Наслідок для авторизації:** будь-яка зміна способу автентифікації зачіпає **3 пакети + конектор**,
+а не один файл як у них. Тому auth — найдорожчий і найважливіший блок: оцінюємо окремо й обережно.
+
+---
+
+## A. Авторизація (найвищий пріоритет, найдорожче)
+
+У `sap-adt-mcp` три способи auth у профілі (`.sap-profiles.json`): `basic`, `certificate`, `kerberos`.
+Системи — **тільки on-prem ADT** (ICM HTTPS 44300). Cloud/BTP (JWT/OAuth) у них немає — тут ми попереду.
+
+| # | Інновація | Як у них | Що дає нам | Куди лягає | Вартість | Буст |
+|---|-----------|----------|------------|------------|----------|------|
+| A1 | **Certificate Auth (Windows Cert Store)** | PowerShell+SChannel bridge, пошук серта по SHA-1 thumbprint, без пароля | Закриває корпоративні on-prem системи, де basic заборонений, а вхід — по клієнтському серту | конектор + clients + broker factory + типи профілю | Висока (3 пакети + конектор, Windows-only, spawn PowerShell) | Високий для enterprise on-prem; нульовий для cloud |
+| A2 | **Kerberos / SPNEGO SSO** | `kerberos` npm, SPN `HTTP@host`, NTLM-detection + hard-reject | Доменний SSO без зберігання пароля — велика зручність і безпека на on-prem | конектор + clients + broker factory | Висока (нативний модуль компілюється з C++, Windows-домен) | Високий для доменних on-prem; вузька аудиторія |
+| A3 | **NTLM-detection guard** | перевірка base64-префікса `TlRMTVNTUAA`, відмова якщо прийшов NTLM замість Kerberos | Захист від тихого фолбеку на слабкий NTLM | конектор | Низька (окрема функція) | Точковий, але дешевий — варто взяти разом з A2 |
+
+**Рекомендація:** спочатку design-spike — описати, як certificate/kerberos лягають на наш broker factory
++ конектор **без ламання** cloud(JWT)/RFC шляхів. Реалізацію A1/A2 — лише після окремого рішення,
+бо ціна висока, а аудиторія вузька (доменні Windows on-prem).
+
+---
+
+## B. Інструменти читання / навігації (середня ціна, хороший буст)
+
+| # | Інновація | Що дає нам | Куди лягає | Вартість | Буст |
+|---|-----------|------------|------------|----------|------|
+| B1 | **`read_signatures`** — лише PUBLIC SECTION класу (методи/типи/константи, без тіл) | 5–20× менший контекст для LLM коли треба лише інтерфейс класу. Прямий burn-rate виграш токенів | handler + clients (парс public section) | Низька–середня | **Високий** — економія токенів на кожному читанні класу |
+| B2 | **`list_method_callers`** — where-used на рівні методу | Точніший impact-аналіз перед зміною методу (не весь клас) | handler + clients (method-level usageReferences) | Середня | Середній — корисно для рефакторингу |
+| B3 | **`get_cds_dependencies` з SQL-метриками** — дерево залежностей CDS + joins/unions/views count + complexity score (LOW…VERY_HIGH) + DCL/ACL стан | Швидка оцінка складності/безпеки CDS без ручного читання | handler + clients (cds dependency graph parse) | Середня | Середній — нішево для CDS-важких проєктів |
+| B4 | **`browse_package` без 500-cap** (до 9999) | Повний лістинг великих пакетів за раз | перевірити, чи в нас є cap; якщо є — підняти | Низька | Низький–середній (залежить чи є в нас обмеження) |
+
+**Рекомендація:** **B1 — взяти першим.** Дешево, прямий і вимірюваний виграш по токенах для будь-якого
+агентного сценарію. B2/B3 — за запитом.
+
+---
+
+## C. Безпека запису / гардрейли (дешево, добрий ROI)
+
+| # | Інновація | Що дає нам | Куди лягає | Вартість | Буст |
+|---|-----------|------------|------------|----------|------|
+| C1 | **`read_table` як SQL Console з guard'ами** — whitelist лише SELECT (блок INSERT/UPDATE/DELETE/MODIFY/CALL/CREATE/DROP/ALTER як перший токен) + blacklist sensitive-таблиць (USR02, USR40, PA000x, T000, RFCDES, DEVACCESS, ICF*) | Безпечний ad-hoc SELECT через ADT SQL Console з захистом від витоку credentials/HR/конфіг даних | handler + clients (sqlConsole endpoint) | Середня | Середній — зручно, але треба ретельні guard'и |
+| C2 | **`namespace` write-guard як middleware** — відхиляє запис до об'єктів не з дозволеним префіксом ще до lock | Захист від випадкового запису поза Z-простором | server middleware / guards | Низька | Середній — дешевий запобіжник |
+| C3 | **per-profile `readonly` + глобальний readonly mode** | Inspection-only режим на рівні профілю/сервера | config + guards | Низька | Середній |
+| C4 | **Mandatory transport для write** | Жодного тихого запису без TR | guards (перевірити чи вже є) | Низька | Залежить від поточного стану |
+
+**Рекомендація:** C2/C3/C4 — дешеві запобіжники, варто звірити з тим, що вже маємо, і добрати відсутнє.
+C1 — корисний, але guard'и треба робити консервативно (краще blacklist + whitelist разом).
+
+---
+
+## D. UX / onboarding (низький пріоритет для нас)
+
+| # | Інновація | Що дає нам | Вартість | Рішення |
+|---|-----------|------------|----------|---------|
+| D1 | **`switch_system`** — runtime-перемикання профілю в одній MCP-сесії | Без рестарту сервера між системами | Середня | Розглянути — у нас multi-session модель може робити це інакше |
+| D2 | **Setup wizard** (`--setup`) з парсингом `SAPUILandscape.xml` + Windows cert listing | Гарний онбординг для desktop-користувача | Висока | Дивимось як ідею, **собі не робимо** — у нас env/конфіг-driven підхід |
+| D3 | **`--standards <file>`** — ін'єкція ABAP coding standards у контекст інструментів | Команда нав'язує naming/error-handling конвенції LLM-у | Низька | **Цікаво — варто розглянути**, дешево й корисно |
+| D4 | **Throttle layer** (acquire/release семафор перед ADT-викликом) | Захист від перевантаження ADT паралельними викликами | Низька–середня | Розглянути якщо ловимо rate-limit/race на ADT |
+
+---
+
+## E. «Дивимось як у людей, але собі точно не робимо»
+
+- **Моноліт-архітектура** (`.sap-profiles.json`, axios усередині сервера) — наш розклад по пакетах
+  дає перевикористання клієнтів поза MCP; назад до моноліту не йдемо.
+- **Setup wizard з парсингом `SAPUILandscape.xml`** (D2) — desktop-онбординг, не наш сценарій.
+- **PowerShell-bridge як єдина реалізація cert-auth** — якщо й робити cert-auth (A1), то крос-платформно
+  через конектор, а не spawn PowerShell.
+- **Прив'язка до Windows** загалом — у них cert/kerberos Windows-only; нам потрібна крос-платформність.
+
+---
+
+## Підсумкова черга (чернетка, обговорюється)
+
+1. **B1 `read_signatures`** — найкращий ROI (токени), низька ціна. Брати першим.
+2. **C2/C3/C4** — звірити наявні гардрейли, добрати дешеві запобіжники.
+3. **A (auth) design-spike** — спроєктувати certificate/kerberos на broker factory + конектор,
+   оцінити реальну ціну по 3 пакетах, **рішення про реалізацію — окремо**.
+4. **D3 `--standards`** — дешево, корисно для команд.
+5. **C1 `read_table`/SQL Console** — за наявності guard-бюджету.
+6. **B2/B3** — за запитом конкретних проєктів.
+7. **D1/D4** — розглянути за потребою.
+
+> Наступний крок: по кожному пункту з 1–6 — окреме рішення «робимо / в який пакет / коли»
+> + (для auth) окремий технічний spike перед будь-яким кодом.

package/docs/superpowers/specs/2026-05-23-cert-kerberos-auth-design.md

@@ -0,0 +1,149 @@
+# Spec: Certificate (mTLS) + Kerberos auth across the ADT connection stack
+
+> Status: design approved, ready for implementation planning.
+> Lifecycle: this spec lives only in `mcp-abap-adt`. **Delete after implementation** — history stays in git.
+> Source of idea: analysis of `sap-adt-mcp` (see `docs/superpowers/plans/innovations-from-sap-adt-mcp.md`, item A).
+
+## 1. Goal & scope
+
+Add two new authentication types to the ADT connection stack:
+
+- **`certificate`** — client-certificate mutual TLS (mTLS), cross-platform, credential material loaded from **files** (PEM or PFX/PKCS#12).
+- **`kerberos`** — SPNEGO/Negotiate SSO, cross-platform via the `kerberos` npm package (GSSAPI on Linux/macOS, SSPI on Windows), as an **optional dependency**.
+
+**In scope:** on-prem ABAP over **HTTP** (`connectionType: 'http'`). Both new types are invalid for `connectionType: 'rfc'` and for BTP cloud (which stays `jwt`).
+
+**Out of scope (explicitly NOT building):**
+- Windows Certificate Store / PowerShell-SChannel bridge (the `sap-adt-mcp` approach). Cross-platform file-based only.
+- NTLM. We hard-reject NTLM tokens if a server offers only NTLM (see Risks).
+- Kerberos mutual-auth multi-leg continuation (see Assumptions).
+- RFC-transport variants of these auth types.
+
+## 2. Architecture decision (the core call)
+
+**Both new auth types bypass `@mcp-abap-adt/auth-broker` and `@mcp-abap-adt/auth-providers` entirely.** The broker's role is narrow: OAuth-style authorization with browser-callback interception. Certificate and Kerberos are non-interactive and transport/connection-level — no browser callback, no broker token lifecycle. They live in the **connection** package (+ types in `interfaces`, + env wiring in the server).
+
+| Type | Pattern | Why |
+|------|---------|-----|
+| **Certificate** | Connection subclass + `httpsAgent` options, with an injected `ICertificateMaterialLoader` for testability | The credential is `cert`+private-key used in the **TLS handshake via `httpsAgent`** — transport-layer, below `getAuthHeaders()`. No header/cookie to "provide". |
+| **Kerberos** | Connection subclass that generates the SPNEGO token **locally** (lazy/optional `kerberos` npm wrapper inside the connection package), sends `Authorization: Negotiate <token>` on the first request, then reuses the SAP session cookie | The Negotiate blob goes into a header, but generation is local GSSAPI (no callback, no refresh lifecycle). No broker, no `ITokenRefresher`, no `BaseTokenProvider`. |
+
+`@mcp-abap-adt/connection` depends only on `interfaces` + `sap-rfc-lite` (not on `auth-providers`), so the SPNEGO wrapper lives in `connection`, keeping that dependency boundary intact.
+
+### Kerberos handshake = single-leg, cookie reuse
+
+`AbstractAbapConnection` already owns CSRF fetch + cookie capture/reuse (`fetchCsrfToken`, cookie merge). `KerberosAbapConnection` generates one AP-REQ for the SPN, sends `Authorization: Negotiate <token>` on the first request, captures the SAP session cookie (`SAP_SESSIONID`/`MYSAPSSO2`), and reuses the cookie thereafter. Single-leg only (no mutual-auth continuation in v1 — see Assumptions).
+
+## 3. Per-package changes
+
+**Three repos** (auth-broker and auth-providers are NOT touched). Listed in dependency (release) order — see §7.
+
+### 3.1 `@mcp-abap-adt/interfaces` (`~/prj/mcp-abap-adt-interfaces`)
+
+- `src/sap/SapAuthType.ts`: extend union →
+  `export type SapAuthType = 'basic' | 'jwt' | 'saml' | 'certificate' | 'kerberos';`
+- `src/sap/ISapConfig.ts`: add optional fields:
+  - Certificate: `certPath?`, `certKeyPath?`, `certPfxPath?`, `certPassphrase?`. (PEM = certPath+certKeyPath; PFX = certPfxPath. Mutually exclusive — validated in connector.)
+  - Kerberos: `kerberosSpn?` (e.g. `HTTP@host.domain`), `kerberosService?` (default `HTTP`).
+- `src/token/ITokenResult.ts`: no shape change needed — kerberos uses existing `tokenType: 'opaque'`. (Optional: add `'kerberos'` to the `tokenType` union for clarity; not required.)
+- New interface `src/auth/ICertificateMaterialLoader.ts`:
+  ```ts
+  export interface ICertificateMaterial { cert?: Buffer|string; key?: Buffer|string; pfx?: Buffer; passphrase?: string; }
+  export interface ICertificateMaterialLoader { load(config: ISapConfig): Promise<ICertificateMaterial>; }
+  ```
+- Export new symbols from `src/index.ts`.
+
+### 3.2 `@mcp-abap-adt/connection` (`~/prj/mcp-abap-connection`) — the connector, heaviest changes
+
+- `src/connection/AbstractAbapConnection.ts`:
+  - In `getAxiosInstance()` (currently builds `new Agent({ rejectUnauthorized })`), add a protected hook:
+    `protected getHttpsAgentOptions(): https.AgentOptions { return {}; }`
+    and merge it into the Agent options. **Important:** the Agent is currently cached on first build; certificate material must be available before the first request (it is — loaded in the cert connection's `connect()`/constructor). Keep `rejectUnauthorized` behavior intact.
+- New `src/connection/CertificateAbapConnection.ts` (extends `AbstractAbapConnection`):
+  - `validateConfig`: requires `connectionType !== 'rfc'`; requires either (`certPath`+`certKeyPath`) or `certPfxPath`; rejects having both PEM and PFX.
+  - Constructor takes an injected `ICertificateMaterialLoader` (default: a file-based impl). `connect()` loads material, then proceeds with normal CSRF fetch.
+  - `getHttpsAgentOptions()` returns `{ cert, key, pfx, passphrase }`.
+  - `buildAuthorizationHeader()` returns `''` (no Authorization header; mTLS identifies the user).
+- New `src/connection/KerberosAbapConnection.ts` (extends `AbstractAbapConnection`):
+  - **Self-contained — no broker, no `ITokenRefresher`, no provider.** Generates the SPNEGO token locally via the connection-local wrapper (below), using the resolved SPN.
+  - `connect()` generates the Negotiate token, sends it on the first request, captures the SAP session cookie via the existing cookie machinery; subsequent requests reuse the cookie.
+  - `buildAuthorizationHeader()` → `Negotiate ${token}` while no session cookie yet; `''` once a cookie exists.
+  - `validateConfig`: requires `connectionType !== 'rfc'`; requires resolvable SPN (`kerberosSpn` or derive `HTTP@<host>` from URL).
+- New `src/auth/FileCertificateMaterialLoader.ts`: reads PEM/PFX from disk → `ICertificateMaterial`. Pure I/O, mockable.
+- New `src/auth/kerberosSpnego.ts`: thin wrapper over the optional `kerberos` npm package (`initializeClient` / `step`), **lazy `import()`**; declared in this package's `optionalDependencies`. The single native, mockable seam. (Lives here, not in auth-providers, because `connection` does not depend on `auth-providers`.)
+- `src/connection/connectionFactory.ts`: add cases:
+  ```ts
+  case 'certificate': return new CertificateAbapConnection(config, logger, sessionId, options?.certLoader);
+  case 'kerberos':    return new KerberosAbapConnection(config, logger, sessionId);
+  ```
+  Keep the existing `connectionType === 'rfc'` early-return guard (rfc wins) — but add validation so cert/kerberos + rfc throws a clear error rather than silently doing RFC.
+- `src/config/sapConfig.ts`: extend `sapConfigSignature()` to include cert paths / SPN (so connection is recreated when these change). Never log key/passphrase contents.
+
+### 3.3 NOT touched: `auth-providers` and `auth-broker`
+
+Certificate and Kerberos bypass both. The broker is only for OAuth-style authorization + browser-callback interception; cert/kerberos are non-interactive and connection-level. **Do not add a `KerberosProvider` to auth-providers, do not modify `AuthBroker`, do not widen the broker's `IConnectionConfig.authType`** — that union is the broker's surface and stays `'basic' | 'jwt' | 'saml'`.
+
+### 3.4 `mcp-abap-adt` (server, this repo)
+
+- `src/lib/config.ts` (lines ~59-75) and `src/lib/utils.ts` (duplicate parser ~1892-1900): extend `SAP_AUTH_TYPE` acceptance to include `'certificate'` and `'kerberos'`. **De-dup opportunity:** these two parsers are copies — extract one shared `parseAuthType()` (recommended while here).
+- Read new env into the assembled `SapConfig`: `SAP_CERT_PATH`, `SAP_CERT_KEY_PATH`, `SAP_CERT_PFX_PATH`, `SAP_CERT_PASSPHRASE`, `SAP_KERBEROS_SPN`, `SAP_KERBEROS_SERVICE`. Document in the help text (~line 1337).
+- **Connection creation path:** find where the server creates an `AbapConnection` for non-broker auth (basic/RFC today) — cert/kerberos follow that same direct `createAbapConnection(...)` path, NOT the broker/`brokerFactory` path. Verify in code during Phase 3; do NOT route cert/kerberos through `brokerFactory`/`IBrokerSessionConfig`.
+- Tool `available_in`: cert/kerberos are connection concerns, not tool capabilities — no tool-level change; but verify nothing assumes `authType ∈ {basic,jwt,saml}`.
+
+## 4. Configuration surface (summary)
+
+`.env` (server-driven, on-prem HTTP):
+```
+SAP_AUTH_TYPE=certificate
+SAP_CERT_PATH=/path/client.crt          # PEM
+SAP_CERT_KEY_PATH=/path/client.key      # PEM
+# or:
+SAP_CERT_PFX_PATH=/path/client.pfx      # PKCS#12
+SAP_CERT_PASSPHRASE=...                  # optional
+```
+```
+SAP_AUTH_TYPE=kerberos
+SAP_KERBEROS_SPN=HTTP@sap-host.corp     # optional; derived from SAP_URL if absent
+```
+
+## 5. Security rules
+
+- Never log private-key bytes, PFX bytes, passphrase, or Negotiate tokens. Safe to log: cert subject/CN, cert path (not contents), SPN, `tokenType`.
+- `sapConfigSignature()` must not embed secret material — use presence flags / hashes, mirroring how it previews tokens today.
+- Reject NTLM: if the server's `WWW-Authenticate` offers only `NTLM` (token begins `TlRMTVNTUAA...`), fail with a clear error rather than negotiating.
+
+## 6. Test plan
+
+Per repo, unit-first (mock the native/IO seams):
+
+- **interfaces**: type-level only (compile).
+- **connection**:
+  - `CertificateAbapConnection`: inject a fake `ICertificateMaterialLoader`; assert `getHttpsAgentOptions()` carries cert/key/pfx; assert no Authorization header; assert PEM-vs-PFX validation and rfc-conflict errors.
+  - `KerberosAbapConnection`: mock the connection-local `kerberosSpnego` wrapper; assert `Authorization: Negotiate <token>` on first request and `''` after a cookie exists; assert cookie capture+reuse; assert rfc-conflict error. No real KDC.
+  - `connectionFactory`: new cases route correctly; cert/kerberos + rfc throws.
+- **server**: `SAP_AUTH_TYPE=certificate|kerberos` parsed (shared `parseAuthType`); cert/kerberos env fields land in the assembled `SapConfig`; connection created via the direct `createAbapConnection` path (not broker).
+- **Integration (live SAP, gated):** one cert smoke + one kerberos smoke against an on-prem system that supports them. Follow CLAUDE.md soft-mode strategy; do not block CI on secrets (see integration-test-env-gates approach).
+
+## 7. Release order (cross-package)
+
+Bottom-up. **The user publishes each package — the agent never runs `npm publish`.** Consumers import published npm versions (not local links), so each step is hard-gated: implement → commit → PR/merge → user publishes → bump consumer to the confirmed version → next step (follow the cross-package-fix-cycle discipline):
+
+1. `interfaces` — union + fields + `ICertificateMaterialLoader`. User publishes, bump everywhere.
+2. `connection` — connection classes + agent hook + cert loader + `kerberosSpnego` (optionalDep) + factory + signature. User publishes.
+3. `mcp-abap-adt` (server) — `parseAuthType` + env→`SapConfig` + direct `createAbapConnection` wiring + docs. Bump deps to the published versions.
+
+(`auth-providers` and `auth-broker` are not in the chain — not touched.) Each step gets its own worktree in its repo (per project workflow: worktrees on all changed code repos; spec stays only here).
+
+## 8. Risks & assumptions
+
+- **A1 — single-leg Negotiate.** Assumes SAP accepts a one-shot AP-REQ then issues a session cookie (typical for Kerberos). If a system demands mutual-auth continuation (`WWW-Authenticate: Negotiate <challenge>` round-trips), the single-token approach does not cover it; would need a continuation hook. **Accepted for v1** (user-confirmed); validate on a live system before claiming kerberos done.
+- **A2 — native build.** `kerberos` npm compiles native bindings (needs GSSAPI dev libs on Linux / build tools on Windows). Mitigated by `optionalDependencies` + lazy import so non-kerberos installs never touch it.
+- **A3 — TGT availability.** Cross-platform kerberos needs a valid TGT in the OS credential cache (`kinit`) or a keytab. Document prerequisite; not auto-provisioned.
+- **A4 — Agent caching.** `getAxiosInstance()` caches the Agent; ensure cert material is loaded before the first request (it is, in `connect()`), else the cached Agent lacks the client cert.
+- **A5 — duplicate auth parser.** `config.ts` and `utils.ts` both parse `SAP_AUTH_TYPE`; both must change. Optional de-dup flagged in §3.5.
+
+## 9. Decisions (resolved)
+
+1. **PEM and PFX both supported** in v1. (user-confirmed)
+2. **Single-leg Negotiate accepted** for v1; no mutual-auth continuation. (user-confirmed)
+3. **cert and kerberos both bypass the broker and auth-providers** — connection-layer only. (user-confirmed)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcp-abap-adt/core",
   "mcpName": "io.github.fr0ster/mcp-abap-adt",
-  "version": "6.8.0",
+  "version": "6.9.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -140,9 +140,9 @@
     "@mcp-abap-adt/auth-broker": "^1.0.5",
     "@mcp-abap-adt/auth-providers": "^1.0.5",
     "@mcp-abap-adt/auth-stores": "^1.0.4",
-    "@mcp-abap-adt/connection": "^1.8.1",
+    "@mcp-abap-adt/connection": "^1.9.0",
     "@mcp-abap-adt/header-validator": "^0.1.8",
-    "@mcp-abap-adt/interfaces": "^7.0.0",
+    "@mcp-abap-adt/interfaces": "^7.2.0",
     "@mcp-abap-adt/logger": "^0.1.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "axios": "^1.14.0",