@mcp-abap-adt/connection 4.0.0 → 5.0.0

package/docs/USAGE.md

@@ -36,7 +36,9 @@ const logger = {
 };
 
 // Create connection (logger is optional)
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 // Or without logger:
 // const connection = createAbapConnection(config);
 
@@ -57,14 +59,27 @@ Tearing the session down is `disconnect()`, but it is not on the
 `IAbapConnection` type this factory returns — see
 [Session Lifecycle](#session-lifecycle) for where it lives and how to reach it.
 
-## Authentication Types
+## Which system, and how you authenticate
+
+Two independent choices, and they must stay independent. The connector says
+which SYSTEM you are dialling; the auth provider says how you prove who you
+are. A communication user against ABAP Cloud and a bearer token against an
+on-prem system are both ordinary, and a design where the credential picked the
+system's session mechanism got one of them wrong whichever way it guessed.
+
+Nothing is detected. `/sap/bc/adt/core/http/sessions` answers on on-prem too,
+and its `DELETE` there leaves the session open while the platform logoff removes
+it — so asking the server would choose the mechanism that releases nothing.
 
 ### Basic Authentication (On-Premise)
 
 For on-premise SAP systems using basic authentication:
 
 ```typescript
-import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+} from '@mcp-abap-adt/connection';
 
 const config = {
   url: 'https://sap-server.local:8000',
@@ -74,7 +89,11 @@ const config = {
   client: '100',
 };
 
-const connection = new BaseAbapConnection(config, logger);
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username, config.password),
+  logger,
+);
 await connection.connect();   // required: nothing is established implicitly
 ```
 
@@ -84,16 +103,25 @@ For SAP BTP ABAP Environment. Token refresh belongs to
 `@mcp-abap-adt/auth-broker`; this package only carries the token:
 
 ```typescript
-import { JwtAbapConnection } from '@mcp-abap-adt/connection';
+import {
+  AdtCloudConnector,
+  TokenAuthProvider,
+} from '@mcp-abap-adt/connection';
 
 const config = {
   url: 'https://tenant.abap.cloud',
   authType: 'jwt' as const,
-  jwtToken: 'eyJhbGciOiJSUzI1NiIs...',
   client: '100', // Optional for cloud
 };
 
-const connection = new JwtAbapConnection(config, logger);
+// A bare token works and has no renewal behind it. Hand the provider an
+// ITokenRefresher instead — from @mcp-abap-adt/auth-broker or your own — and it
+// checks expiry and refreshes on its own.
+const connection = new AdtCloudConnector(
+  config,
+  new TokenAuthProvider('eyJhbGciOiJSUzI1NiIs...'),
+  logger,
+);
 await connection.connect();   // required: nothing is established implicitly
 
 // Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
@@ -172,7 +200,9 @@ await connection.makeAdtRequest({
 By default, connections are stateless - each request gets fresh cookies and CSRF tokens:
 
 ```typescript
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 await connection.connect();
 
 // Each request is independent
@@ -184,7 +214,9 @@ await connection.makeAdtRequest({ method: 'GET', url: '/sap/bc/adt/discovery' })
 Enable stateful session mode for operations requiring consistent session state:
 
 ```typescript
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 await connection.connect();
 
 // Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
@@ -242,7 +274,7 @@ implied. Four things follow from it.
 > site:
 >
 > ```typescript
-> const conn = new BaseAbapConnection(config, logger);
+> const conn = new AdtOnPremConnector(config, provider, logger);
 > tearDownAfter(conn);                       // ✅ checked
 > tearDownAfter(new RfcAbapConnection(cfg)); // ✅ compile error, as it should be
 > ```
@@ -290,9 +322,13 @@ implied. Four things follow from it.
 ### connect() is required, and it tells the truth
 
 ```typescript
-import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+import { AdtOnPremConnector, BasicAuthProvider } from '@mcp-abap-adt/connection';
 
-const connection = new BaseAbapConnection(config, logger);
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(user, pass),
+  logger,
+);
 
 await connection.connect();          // establishes the session, or rejects
 connection.isConnected();            // true only while a usable session exists
@@ -420,7 +456,9 @@ yours.
 Session IDs are auto-generated (UUID) when connection is created:
 
 ```typescript
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 console.log(connection.getSessionId()); // e.g., '7f3a8b2c-...'
 
 // Or provide your own when creating connection
@@ -434,7 +472,9 @@ Dynamically switch between stateful and stateless modes:
 
 ```typescript
 // Start in stateless mode (default)
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 await connection.connect();
 
 // Enable stateful for a series of operations
@@ -447,14 +487,20 @@ await connection.makeAdtRequest({ method: 'POST', url: '...' });
 connection.setSessionType('stateless');
 ```
 
-### Connection Reset
+### Starting Over
 
-Reset connection state (clears cookies, CSRF token):
+There is no local-only reset. Discarding the cookie does not end the ABAP
+session — the server keeps it until its own timeout, and sessions are limited
+per user — so starting over means telling the server, then connecting again:
 
 ```typescript
-connection.reset();
+await connection.disconnect(); // ends the session on the server too
+await connection.connect(); // a new one, explicitly
 ```
 
+A connection that was connected must be disconnected, which is why this belongs
+in a `finally`. `disconnect()` never throws, so it is safe there.
+
 ## Custom Logging
 
 ### Using Custom Logger
@@ -493,7 +539,9 @@ class CustomLogger implements ILogger {
 }
 
 const logger = new CustomLogger();
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 ```
 
 ## Error Handling
@@ -577,16 +625,38 @@ interface AbapConnection {
 }
 ```
 
-Anything beyond that is **not** on the contract. `reset()`, `getSessionMode()`
+Anything beyond that is **not** on the contract. `getSessionMode()`
 and the session lifecycle (`disconnect()`, `isConnected()`,
 `getSessionIdentity()`) live on the HTTP
 connection classes; `RfcAbapConnection` has some of them and not others, so
 reach for them through a concrete type rather than through what
 `createAbapConnection()` returns.
 
-### `BaseAbapConnection` (Basic Auth)
+### `AdtOnPremConnector` / `AdtCloudConnector`
+
+One per system, each handed an auth provider:
+
+```typescript
+class AdtOnPremConnector extends CredentialAbapConnection {
+  constructor(
+    config: SapConfig,
+    provider: IAuthProvider,
+    logger?: ILogger | null,
+    sessionId?: string,
+  );
+}
+// AdtCloudConnector has the same shape.
+```
+
+The difference is what each does with the session: on-prem takes it from the
+establishing call and gives it back with the platform's ICF logoff; cloud opens
+one at `/sap/bc/adt/core/http/sessions` and gives it back by `DELETE` on the
+address the server publishes.
+
+### `BaseAbapConnection` (Basic Auth) — deprecated
 
-For on-premise SAP systems:
+The previous shape, where the class stated the credential. Still works; see
+[Migration to 5.0](./MIGRATION-5.0.md).
 
 ```typescript
 class BaseAbapConnection extends AbstractAbapConnection {
@@ -670,7 +740,7 @@ export class CloudSdkAbapConnection {
 ```
 
 
-### `JwtAbapConnection` (JWT/OAuth2)
+### `JwtAbapConnection` (JWT/OAuth2) — deprecated
 
 For SAP BTP cloud systems. Token refresh is handled by `@mcp-abap-adt/auth-broker`:
 

package/docs/superpowers/specs/2026-08-21-platform-connectors.md

@@ -0,0 +1,108 @@
+# Two connectors, one credential contract
+
+**Status:** draft, for review
+**Subject:** `AdtOnPremConnector` / `AdtCloudConnector` over a shared base, with authentication passed in rather than inherited.
+
+## Why
+
+The class you take today states your **credential**, and the session mechanism rides along with it. `JwtAbapConnection` is the only class that overrides `createSessionStrategy()`, so:
+
+| the consumer builds | on a **cloud** host | on an **on-prem** host |
+|---|---|---|
+| `authType: 'jwt'` | ADT session resource — correct | ADT session resource — wrong |
+| `authType: 'basic'` | ICF logoff — wrong | ICF logoff — correct |
+| `authType: 'saml'` | ICF logoff — wrong | correct |
+| `authType: 'certificate'`, `'kerberos'` | ICF logoff — wrong | correct |
+
+Both wrong rows are reachable. The cloud trial answers `www-authenticate: Basic`, so a communication user against ABAP Cloud is an ordinary setup; SAML is the usual interactive logon on BTP. And the mirror — JWT against an on-prem system — puts that system on a mechanism it does not use.
+
+**The consumer knows which system it is dialling.** It should say so by taking the connector for it, and the credential should be a parameter of that choice rather than the thing making it.
+
+### Why not detect it
+
+Tried, measured, wrong. `/sap/bc/adt/core/http/sessions` was probed to decide the mechanism; **on-prem answers it too** — 200, a `SAP_SESSIONID`, and a document publishing *both* the session resource and `/sap/public/bc/icf/logoff`. The probe never told the two systems apart; it told whether an endpoint exists, and both have it, so on-prem was silently moved onto the cloud mechanism.
+
+Nothing here goes back to asking the server which kind of system it is.
+
+## The shape
+
+```
+AbstractAbapConnection            requests, CSRF, cookies, session lifecycle, admission
+        │
+        ├── AdtOnPremConnector    session arrives with the establishing call;
+        │                         given back with the platform's ICF logoff
+        │
+        └── AdtCloudConnector     session opened at /sap/bc/adt/core/http/sessions
+                                  (`x-sap-security-session: create`,
+                                   `sap-adt-purpose: preflight_logon`);
+                                  given back by DELETE on the address it published
+```
+
+Both take a **credential** object. The two session strategies already exist and do not change; what changes is who chooses them and how authentication arrives.
+
+## The credential contract
+
+`ITokenRefresher` and `ITokenProvider` already exist in `@mcp-abap-adt/interfaces` — the first says outright *"Created by AuthBroker for a specific destination. Injected into JwtAbapConnection to enable automatic token refresh."* — and `@mcp-abap-adt/auth-providers` ships twelve implementations. That is the seam to join, not to reinvent.
+
+But both are about **tokens**, and only one of the five ways in works that way. Measured, every current class overrides exactly two members, plus a few extras:
+
+| | `buildAuthorizationHeader` | `establishSession` | other |
+|---|---|---|---|
+| basic | ✓ | ✓ | — |
+| jwt | ✓ | ✓ | `prepareCredential`, `ensureToken` |
+| saml | ✓ | ✓ | — |
+| certificate | ✓ | ✓ | `getHttpsAgentOptions`, `ensureMaterial` |
+| kerberos | ✓ | ✓ | `fetchCsrfToken` |
+
+So the contract is small and is **not** "give me a token":
+
+```ts
+interface IAbapCredential {
+  /** Prepare before anything is sent — mint, load, unlock. Optional. */
+  prepare?(): Promise<void>;
+  /** The Authorization header value, or '' when the credential is not a header. */
+  authorizationHeader(): string;
+  /** TLS material, for credentials that are a certificate rather than a header. */
+  httpsAgentOptions?(): AgentOptions;
+}
+```
+
+A token provider becomes one implementation of it, wrapping `ITokenRefresher`. Basic wraps a username and password. Certificate returns no header and supplies agent options instead.
+
+**Where it lives:** `@mcp-abap-adt/interfaces`, released before the connector consumes it — the standing rule, no local bridge.
+
+## The hard part, named
+
+`JwtAbapConnection` is 483 lines and **most of it is not authentication.** `renewalInFlight`, the `AsyncLocalStorage` operation scopes, `tokenGeneration` against `recoveredGeneration`, `ensureRecovered`, and the calls to `discardSession()` and `recoverSession()` are about what happens to *the session* when the credential is renewed mid-flight. That is connection business and stays in the base.
+
+The split to make:
+
+- **credential**: "get me a valid token" → the provider, behind `IAbapCredential`;
+- **connection**: "the credential changed, so the session it built is gone — discard, re-establish, let the request retry once" → the base, unchanged in behaviour.
+
+If this line is drawn wrongly the 4.0.0 work is undone, and that work exists because the failures it fixed were subtle: two layered single-flight promises, identity-checked clears, an epoch checked before a retry. **The spec's success condition is that every test from 4.0.0 passes untouched.**
+
+## Migration
+
+The five current classes stay, deprecated, as thin wrappers: `new JwtAbapConnection(config, logger, sessionId, refresher)` builds `AdtCloudConnector` with a token credential. Nothing published breaks, and `createAbapConnection()` keeps working from `SapConfig` alone.
+
+New code takes a connector and hands it a credential.
+
+## What this does not do
+
+- **No auto-detection**, in any form — see above.
+- **No change to the two session strategies.** They were measured against a live trial and an on-prem system and are not the subject here.
+- **No new auth mechanism.** Only a place for the ones that exist to be passed in.
+- **No dependency on the auth packages.** The connector keeps speaking contracts; consumers supply implementations, as with `IAbapConnection` today.
+
+## Open, to settle in review
+
+1. **`prepare()` and Kerberos.** SPNEGO deliberately does not prepare early: minting the token sooner changes when the exchange happens, and that path is not production-tested. Does Kerberos keep opting out, or does the contract grow a way to say "prepare late"?
+2. **What `createAbapConnection(config)` does when the config does not say which system it is.** Defaulting to on-prem keeps every existing consumer working and never guesses; refusing is more honest and breaks them. Deprecation-shaped default seems right, but it is a decision.
+3. **Whether `AdtOnPremConnector` should refuse the ADT session resource explicitly** — it exists there and answers, so a future edit could quietly start using it.
+
+## How it gets verified
+
+- Cloud: from this machine, against the BTP trial — connect, hold a session across stateful requests, disconnect. Already the way the current mechanism was measured.
+- On-prem: not reachable from here. Reviewed and run on the machine that reaches a system, as PR #34 was: strategy `icf`, `lock → PUT` chains, session present, and **no request to the session resource**.
+- Both wrong rows from the table above become tests: a cloud connector with a basic credential must use the ADT session; an on-prem connector with a token credential must not.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/connection",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "ABAP connection layer for MCP ABAP ADT server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",