@mcp-abap-adt/connection 5.0.0 → 6.0.0

package/CHANGELOG.md

@@ -7,6 +7,138 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.0.0] - 2026-08-24
+
+The wire owns what is the wire's, and the factory and per-credential classes are
+gone. See [Migration to 6.0](./docs/MIGRATION-6.0.md).
+
+### Added
+
+- **The transport axis is complete and public.** `IAdtTransport` now covers
+  everything true of a wire — carrying a request, addressing it, establishing
+  itself, and whatever session state it keeps — and both ends are objects:
+  `HttpTransport` and `RfcTransport`. `IAdtEstablishContext`, `IRfcConversation`
+  and `RfcConnectionParams` are exported, so a caller handed a seam can name it.
+
+- **`rfcConversationFrom(config)`** — the front door to the RFC wire. Derives
+  `ashost` from the url and `sysnr` from the HTTP port (`80XX` → `XX`, with
+  `SAP_SYSNR` overriding), and loads the SAP NW RFC SDK only when a conversation
+  opens, so a machine without it fails at `connect()` rather than at
+  construction.
+
+- **`RfcTransport` supplies a default `Accept`.** axios adds one over HTTP and
+  nobody had noticed; ADT refuses a request without it with
+  `400 ExceptionResourceBadRequest: Accept header missing`.
+
+### Changed
+
+- **The on-prem connector works over RFC.** It did not, at all. Measured against
+  a real system, three blockers stood one behind the other, all of them HTTP
+  assumptions in the class every connector shares: the CSRF fetch handed
+  `SADT_REST_RFC_ENDPOINT` an absolute URL and dumped it with
+  `STRING_OFFSET_TOO_LARGE`; that endpoint returns no `x-csrf-token` however it
+  is asked, so the exchange could not succeed; and the session fingerprint was a
+  scan for a `SAP_SESSIONID` cookie, so a wire that issues none read as a
+  connection the server had opened no session for.
+
+  The base class did not merely check for cookies — it DEFINED a session as one.
+
+- **`AbstractAbapConnection` keeps the lifecycle and nothing else** (1989 → ~1620
+  lines): the transition queue, teardown epochs, session generations, critical
+  sections, stale-request fencing, 401 classification, the identity policy, and
+  the promise that `disconnect()` settles. Cookies, the cookie jar, the CSRF
+  exchange, affinity headers, axios and addressing all moved to the wire that
+  has them. There is no `if (transport is rfc)` anywhere.
+
+- **A credential refused surfaces** rather than being renewed behind the caller —
+  on `connect()` and on the request path alike. Renewal is the provider's, and it
+  happens on an expiry the provider can see, on every call that asks for a header.
+  See *Removed*, below: nothing here answers a 401 any more.
+
+### Changed — BREAKING
+
+- **The base classes ask nothing.** `AbstractAbapConnection` and
+  `CredentialAbapConnection` contain no config-driven conditional, no optional-member
+  call, and no dispatch on a type or a shape. What a collaborator can do is stated by
+  its type, not discovered at runtime:
+
+  - `IAdtTransport.open()` / `close()` are required — a wire with nothing to open
+    writes an empty method, which is true of it;
+  - `IAuthProvider.prepare()`, `cookies()` and `transportMaterial()` are required for
+    the same reason (needs `@mcp-abap-adt/interfaces` 20.0.0);
+  - `establish()` is the transport's, and the connection delegates to it without
+    asking anything first. The credential contributes a header, cookies and TLS
+    material; earning a CSRF token is the wire's work, because the wire is what
+    holds the session the token is bound to (needs `@mcp-abap-adt/interfaces`
+    21.0.0, where the two credential atoms leave the contract — nothing
+    implemented them);
+  - `skipSessionType` is gone: it described BASIS 7.40, and a deployment is a wire, so
+    it is `LegacyOnPremHttpTransport`;
+  - whether a session exists is `IAdtTransport.sessionEstablished()` — a verdict each
+    wire gives about itself, instead of the connection reading a fingerprint and a flag
+    and deciding for all of them at once.
+
+  A credential you wrote gains three usually-empty members; see
+  [the migration guide](./docs/MIGRATION-6.0.md#writing-your-own-credential).
+
+### Removed
+
+- **The connection no longer answers a `401` for you.** It called `renew()` on the
+  credential, compared the header against the previous one, and rebuilt the session
+  if it had changed — a credential lifetime managed from inside the connection.
+  Renewal on an expiry the provider can SEE still happens, inside
+  `authorizationHeader()`, which is asked per request; the other case — a token the
+  provider still believes in and the server refuses — is a judgement made with what
+  the caller knows, so the refusal surfaces. A refused credential is not a lost
+  session, so the connection stays usable. `TokenAuthProvider` declares
+  `IRenewableCredential` (interfaces 19.0.0), which is what a consumer narrows to
+  before calling `renew()` itself.
+
+- **`disconnect({ deadlineMs })`** takes no arguments, and `SAP_RELEASE_DEADLINE_MS`
+  is gone with it. The parameter bounded a wait for the goodbye to be *answered*,
+  and the method does not act on that answer: it tells the server the session is
+  finished, and whether and when the session is freed is the server's affair. The
+  default was already `0`. Waiting bought a caller nothing while being the one
+  thing that could make a teardown unbounded — the goodbye carries no request
+  timeout by design, so a server that never answered would have held the teardown
+  for the whole deadline. Needs `@mcp-abap-adt/interfaces` 18.0.0, where the
+  parameter leaves the contract. Verified against a live BTP trial before the
+  contract moved: `disconnect()` returned in 1 ms and the goodbye still went out.
+
+- **`SessionStrategy`** and its two implementations. A session mechanism only some
+  wires have, described from inside the class every wire shares and driven by the
+  connection — a second wire abstraction beside `IAdtTransport`. It is the
+  transport's `open()`/`close()` now, which is also what made `connect()` possible
+  over RFC at all.
+
+- **`createAbapConnection()`** and the connection classes it built:
+  `BaseAbapConnection` (`OnPremAbapConnection`), `JwtAbapConnection`
+  (`CloudAbapConnection`), `SamlAbapConnection`, `CertificateAbapConnection`,
+  `KerberosAbapConnection`, `RfcAbapConnection` — 1597 lines. Take a connector,
+  hand it a credential, and hand it a transport — which has no default, because
+  which wire you are on is not something to guess.
+
+- `adaptTransport()`, which dressed a transport in an axios shape so six call
+  sites did not have to be rewritten. They were rewritten.
+
+- `connectionType: 'rfc'` as a way to reach the RFC wire. The wire is an
+  argument now.
+
+  **Kerberos has no direct replacement.** It was single-leg only and untested
+  against a live KDC (#35); a `KerberosAuthProvider` belongs on the credential
+  axis and should be added with a system to test it against.
+
+### Fixed
+
+- Credential cookies are merged into the establishing request rather than
+  overwritten by the wire's own — a SAML session IS that cookie, and replacing
+  it sent the exchange out unauthenticated.
+- The CSRF fallback endpoint is tried only when the primary answers 404. A host
+  that is not answering will not answer a different path, and asking doubled the
+  wait before the real error surfaced.
+- A CSRF token arriving on a refused response (405, or any refusal carrying the
+  header) is kept instead of thrown away by the retry.
+
 ## [5.0.0] - 2026-08-21
 
 A connection now says which system it is, closes what it opens, and is handed its
@@ -1120,7 +1252,8 @@ const connection = createAbapConnection(config, logger);
 - JWT token refresh now properly handles connection errors (401/403 during initial connect)
 - Permission errors (403 with "ExceptionResourceNoAccess") no longer trigger JWT refresh loops
 - Proper separation: base class handles HTTP/session, concrete classes handle auth-specific errors
-[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v5.0.0...HEAD
+[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v6.0.0...HEAD
+[6.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v5.0.0...v6.0.0
 [5.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v4.0.0...v5.0.0
 [4.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v3.0.0...v4.0.0
 [3.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v2.0.0...v3.0.0

package/README.md

@@ -57,13 +57,23 @@ The package uses a clean separation of concerns:
 - **Auth providers** (`BasicAuthProvider`, `TokenAuthProvider`, `SamlAuthProvider`,
   `CertificateAuthProvider`):
   - What a connection authenticates with, passed in
-  - A token provider renews on its own; the connector asks it per request and, on a
-    `401`, tells it the answer was refused before asking again
-
-- **`BaseAbapConnection`, `JwtAbapConnection`, `SamlAbapConnection`,
-  `CertificateAbapConnection`, `KerberosAbapConnection`** (deprecated, still exported):
-  - The previous shape, where the class stated your credential and the session
-    mechanism came with it. See [Migration to 5.0](./docs/MIGRATION-5.0.md)
+  - A token provider renews on its own, and the connector asks it per request — which
+    is how a token that expired between two requests is replaced with nobody
+    deciding to replace it
+  - A `401` **surfaces**. Whether a refusal meant "the token is stale" or "these
+    credentials are refused" is a judgement made with what you know, so the
+    connector does not answer it for you. A credential that can be told to get a
+    new one says so through `IRenewableCredential`, which you narrow to
+
+- **Transports** (`OnPremHttpTransport`, `CloudHttpTransport`, `RfcTransport`):
+  - What a request travels over, and everything that is true of that wire.
+    `HttpTransport` keeps the cookie jar, the CSRF token and the affinity
+    headers; `RfcTransport` translates into `SADT_REST_RFC_ENDPOINT` and keeps a
+    conversation that IS the session
+  - On-prem is where this is a real choice; ABAP Cloud has one wire and its
+    connector takes no such parameter
+  - `rfcConversationFrom(config)` builds what `RfcTransport` needs, deriving
+    `ashost` and `sysnr` and loading the SDK only when a conversation opens
 
 - **`GenericWebSocketTransport`** (concrete, exported):
   - Transport abstraction for realtime WS message flows
@@ -123,6 +133,7 @@ This package interacts with external packages **ONLY through interfaces**:
 
 - 📦 **[Installation Guide](./docs/INSTALLATION.md)** - Setup and installation instructions
 - 📚 **[Usage Guide](./docs/USAGE.md)** - Detailed usage examples and API documentation
+- 🚚 **[Migration to 6.0.0](./docs/MIGRATION-6.0.md)** - the factory and the per-credential classes are removed; RFC is a transport, not a class
 - 🚚 **[Migration to 4.0.0](./docs/MIGRATION-4.0.md)** - a 401 refreshes the token, a 403 reaches you with the server's message; the synthesised "JWT token has expired" is gone
 - 🚚 **[Migration: the explicit session lifecycle](./docs/MIGRATION-2.0.md)** - `connect()` is now required; start here if you are coming from 1.x
 - 💡 **[Examples](./examples/)** - Working code examples
@@ -149,7 +160,13 @@ For detailed installation instructions, see [Installation Guide](./docs/INSTALLA
 ### Basic Usage (On-Premise)
 
 ```typescript
-import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  OnPremHttpTransport,
+  SapConfig,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
 const config: SapConfig = {
   url: "https://your-sap-system.com",
@@ -167,23 +184,37 @@ const logger = {
   debug: (msg: string, meta?: any) => console.debug(msg, meta),
 };
 
-// Create connection
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+// Which system you are dialling is the class you take; which credential it
+// authenticates with is the object you hand it. Neither is detected.
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();   // required before any request
 
 // Make ADT request
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
 ### Cloud Usage (JWT/OAuth2)
 
 ```typescript
-import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
+import {
+  AdtCloudConnector,
+  CloudHttpTransport,
+  SapConfig,
+  TokenAuthProvider,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
 // JWT configuration
 const config: SapConfig = {
@@ -200,23 +231,77 @@ const logger = {
   debug: (msg: string, meta?: any) => console.debug(msg, meta),
 };
 
-// Logger is optional - if not provided, no logging output
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "cloud", // which SYSTEM this is — said, never detected
-});
+// Logger is optional - if not provided, no logging output.
+// A bare string is a token with nothing behind it. Hand `TokenAuthProvider` an
+// `ITokenRefresher` instead and it checks expiry and renews on its own, which
+// is what you want in anything long-lived.
+const connection = new AdtCloudConnector(
+  config,
+  new TokenAuthProvider(config.jwtToken!),
+  new CloudHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();
 
-// Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
+// Note: obtaining and refreshing tokens is @mcp-abap-adt/auth-broker's job
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
+### On-Premise over RFC
+
+The same ADT calls, over `SADT_REST_RFC_ENDPOINT` — the function module Eclipse
+ADT itself uses through JCo — instead of over HTTP. Worth taking on a system
+where stateful HTTP sessions are not usable: an RFC conversation is one ABAP
+session for its whole lifetime, which is the way past `423 invalid lock handle`
+on BASIS < 7.50.
+
+Needs the SAP NW RFC SDK on the machine and `npm install @mcp-abap-adt/sap-rfc-lite`.
+
+```typescript
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  RfcTransport,
+  rfcConversationFrom,
+} from "@mcp-abap-adt/connection";
+
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new RfcTransport(rfcConversationFrom(config), logger),
+  logger,
+);
+
+await connection.connect();
+// Everything above the wire is the same: makeAdtRequest, setSessionType,
+// disconnect. What differs is where the session lives — see below.
+```
+
+**Where to look for it.** An HTTP session is an ICF session and appears in
+**SM05**. An RFC conversation is a gateway client: it appears in **SMGW → Logged
+on Clients** as `NWRFC`, and never in SM05, because there is no ICM in that
+path. Looking for one in the other monitor and finding nothing is not a fault.
+
+There is no cloud equivalent: ABAP Cloud has one wire, and `AdtCloudConnector`
+takes no transport parameter at all.
+
 ### SSO Usage (SAML Session Cookies)
 
 ```typescript
-import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
+import {
+  AdtOnPremConnector,
+  OnPremHttpTransport,
+  SamlAuthProvider,
+  SapConfig,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
 const config: SapConfig = {
   url: "https://your-sap-system.com",
@@ -224,34 +309,49 @@ const config: SapConfig = {
   sessionCookies: "MYSAPSSO2=...; SAP_SESSIONID=...",
 };
 
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+// The cookies ARE the credential here — there is no Authorization header at all.
+const connection = new AdtOnPremConnector(
+  config,
+  new SamlAuthProvider(config.sessionCookies!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();
 
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
 ### Cloud Usage with Automatic Token Refresh
 
-For automatic token refresh on **401** errors, inject `ITokenRefresher`:
+Give `TokenAuthProvider` an `ITokenRefresher` and the provider replaces an
+**expired** token on its own — it is asked per request and checks expiry before
+answering, so nobody decides to renew. A token the source still believes in and
+the server refuses is the other half, and that one **surfaces**:
 
 ```typescript
 import {
   AdtCloudConnector,
-  TokenAuthProvider,
+  CloudHttpTransport,
   SapConfig,
+  TokenAuthProvider,
+  getTimeout,
 } from "@mcp-abap-adt/connection";
 import type { ITokenRefresher } from "@mcp-abap-adt/interfaces";
 
 // Token refresher provides token acquisition and refresh
 // (created by @mcp-abap-adt/auth-broker or custom implementation)
+const currentAccessToken = 'the access token you already hold';
+const exchangeRefreshToken = async () => 'a freshly exchanged access token';
 const tokenRefresher: ITokenRefresher = {
-  getToken: async () => { /* return current token */ },
-  refreshToken: async () => { /* refresh and return new token */ },
+  getToken: async () => currentAccessToken,      // the one you hold
+  refreshToken: async () => exchangeRefreshToken(), // a new one, and cache it
 };
 
 const config: SapConfig = {
@@ -264,19 +364,24 @@ const config: SapConfig = {
 const connection = new AdtCloudConnector(
   config,
   new TokenAuthProvider(tokenRefresher),
+  new CloudHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
   logger,
 );
 await connection.connect();
 
-// On a 401 the connector tells the provider its token was refused, asks again,
-// and only if the answer changed rebuilds the session and retries once. An
-// unchanged answer means the server refused these credentials, and the 401
+// On a 401 nothing here decides to get a new credential: the refusal reaches
+// you. Whether it meant "stale" is a judgement made with what you know, and
+// `renew()` is the seam you make it with. The session is untouched — a refused
 // reaches you. A refresh replaces the SAP session, so if a lock window is open
 // the request fails with ADT_SESSION_REPLACED rather than continuing on a
 // session your lock is not in.
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
@@ -297,11 +402,22 @@ See [MIGRATION-4.0.md](./docs/MIGRATION-4.0.md).
 For operations that require session state (e.g., object modifications), you can enable stateful sessions:
 
 ```typescript
-import { createAbapConnection } from "@mcp-abap-adt/connection";
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  OnPremHttpTransport,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();
 
 // Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
@@ -312,6 +428,7 @@ await connection.makeAdtRequest({
   method: "POST",
   url: "/sap/bc/adt/objects/domains",
   data: { /* domain data */ },
+  timeout: getTimeout("default"),
 });
 
 // Note: Session state persistence is handled by @mcp-abap-adt/auth-broker package
@@ -320,7 +437,7 @@ await connection.makeAdtRequest({
 ### Custom Logger
 
 ```typescript
-import { ILogger } from "@mcp-abap-adt/connection";
+import { AdtOnPremConnector, BasicAuthProvider, ILogger, OnPremHttpTransport } from "@mcp-abap-adt/connection";
 
 class MyLogger implements ILogger {
   info(message: string, meta?: any): void {
@@ -349,9 +466,15 @@ class MyLogger implements ILogger {
 }
 
 const logger = new MyLogger();
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 ```
 
 ## CLI Tool
@@ -441,6 +564,8 @@ type SapConfig = {
 Main interface for ABAP connections.
 
 ```typescript
+import { AbapRequestOptions } from '@mcp-abap-adt/connection';
+import type { AxiosResponse } from 'axios';
 // The shared contract (IAbapConnection), what every connection provides:
 interface AbapConnection {
   connect(): Promise<void>; // REQUIRED before any request; rejects on failure
@@ -451,10 +576,12 @@ interface AbapConnection {
 }
 ```
 
-The HTTP connection classes carry the rest of the session lifecycle. It is on the
-shared contract as a **capability atom** in `@mcp-abap-adt/interfaces` rather than
-as methods on `IAbapConnection`, which is why `RfcAbapConnection` — a transport
-that owns no HTTP session — is unaffected by its existence:
+The connectors carry the rest of the session lifecycle. It is on the shared
+contract as a **capability atom** in `@mcp-abap-adt/interfaces` rather than as
+methods on `IAbapConnection`, so a consumer that only carries requests is
+unaffected by its existence. Note that a connection over RFC has the whole of it
+— what an RFC conversation has none of is a session RESOURCE to open and close
+by address, which is an empty mechanism, not an absent lifecycle:
 
 ```typescript
 // ISessionLifecycleAware
@@ -496,16 +623,35 @@ interface ILogger {
 
 ### Functions
 
-#### `createAbapConnection(config, logger?, sessionId?)`
+#### `rfcConversationFrom(config)`
 
-Factory function to create an ABAP connection instance.
+What `RfcTransport` is constructed with. Derives `ashost` from the url and
+`sysnr` from the HTTP port by the SAP convention that `80XX` is the ICM port for
+system `XX`, which `SAP_SYSNR` overrides for a port that follows no convention.
+
+The SAP NW RFC SDK is loaded when a conversation opens, not when this is called,
+so a machine without it fails at `connect()` with a message saying what to
+install rather than at construction.
+
+```text
+function rfcConversationFrom(config: SapConfig): () => IRfcConversation;
+function rfcParamsFrom(config: SapConfig): RfcConnectionParams;
+```
 
 ```typescript
-function createAbapConnection(
-  config: SapConfig,
-  logger?: ILogger | null,
-  sessionId?: string
-): AbapConnection;
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  RfcTransport,
+  rfcConversationFrom,
+} from "@mcp-abap-adt/connection";
+
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new RfcTransport(rfcConversationFrom(config), logger),
+  logger,
+);
 ```
 
 #### `CSRF_CONFIG` and `CSRF_ERROR_MESSAGES`
@@ -532,6 +678,12 @@ import { CSRF_CONFIG, CSRF_ERROR_MESSAGES } from '@mcp-abap-adt/connection';
 ```typescript
 import { CSRF_CONFIG, CSRF_ERROR_MESSAGES } from '@mcp-abap-adt/connection';
 
+// Whatever HTTP client your own connection class is built on.
+const yourHttpClient = {
+  get: async (url: string, config: { headers: Record<string, string> }) =>
+    ({ headers: {} as Record<string, string> }),
+};
+
 async function fetchCsrfToken(baseUrl: string): Promise<string> {
   const csrfUrl = `${baseUrl}${CSRF_CONFIG.ENDPOINT}`;
   
@@ -563,6 +715,10 @@ async function fetchCsrfToken(baseUrl: string): Promise<string> {
       await new Promise(resolve => setTimeout(resolve, CSRF_CONFIG.RETRY_DELAY));
     }
   }
+
+  // Unreachable: the last attempt either returns or throws above. Stated so the
+  // function has a return type the compiler can agree with.
+  throw new Error(CSRF_ERROR_MESSAGES.NOT_IN_HEADERS);
 }
 ```
 

package/dist/auth/providers.d.ts

@@ -7,16 +7,20 @@
  * `CertificateAuthProvider` returns are what `CertificateAbapConnection`
  * returned. Nothing about how a credential works changed; only who owns it.
  */
-import type { AgentOptions } from 'node:https';
-import type { ICertificateMaterialLoader, ISapConfig, ITokenRefresher } from '@mcp-abap-adt/interfaces';
-import type { IAuthProvider } from './IAuthProvider.js';
+import type { IAuthProvider, ICertificateMaterial, ICertificateMaterialLoader, IRenewableCredential, ISapConfig, ITokenRefresher } from '@mcp-abap-adt/interfaces';
 /** Username and password, as `Basic base64(user:pass)`. */
 export declare class BasicAuthProvider implements IAuthProvider {
     private readonly username;
     private readonly password;
     readonly kind = "basic";
+    /** Nothing to get ready: this credential is complete as constructed. */
+    prepare(): Promise<void>;
+    /** Not cookies. This one authenticates with a header. */
+    cookies(): string | null;
+    /** No TLS material: this credential lives in a header, not in the transport. */
+    transportMaterial(): ICertificateMaterial;
     constructor(username: string, password: string);
-    authorizationHeader(): Promise<string>;
+    authorizationHeader(): Promise<string | null>;
 }
 /**
  * A bearer token, kept current by whoever issued it.
@@ -30,9 +34,15 @@ export declare class BasicAuthProvider implements IAuthProvider {
  * credential behind it is renewed mid-flight is the connection's business and
  * stays there; see `JwtAbapConnection`, which still owns that machinery.
  */
-export declare class TokenAuthProvider implements IAuthProvider {
+export declare class TokenAuthProvider implements IRenewableCredential {
     private readonly source;
     readonly kind = "token";
+    /** Nothing to get ready: this credential is complete as constructed. */
+    prepare(): Promise<void>;
+    /** Not cookies. This one authenticates with a header. */
+    cookies(): string | null;
+    /** No TLS material: this credential lives in a header, not in the transport. */
+    transportMaterial(): ICertificateMaterial;
     /**
      * A token, or something that can produce one.
      *
@@ -50,10 +60,21 @@ export declare class TokenAuthProvider implements IAuthProvider {
      * stale one and hide exactly the renewal the provider exists to do — which
      * is what the first version of this class did.
      */
-    authorizationHeader(): Promise<string>;
+    authorizationHeader(): Promise<string | null>;
     /**
      * The token was refused, so force a new one.
      *
+     * Declared through `IRenewableCredential` rather than as an optional member
+     * of every credential, so a consumer narrows to it: a password has nothing
+     * behind it to ask again, and a SAML session was negotiated elsewhere.
+     *
+     * **Nothing in this package calls it.** A token that EXPIRED is replaced
+     * inside `authorizationHeader()` above, which is asked per request — nobody
+     * decides anything. This is the other case, a token the source still believes
+     * in and the server refuses, and whether a refusal meant that is a judgement
+     * made with what the caller knows. So the refusal surfaces, and this is the
+     * seam the caller decides with.
+     *
      * `getToken()` is documented to return the cached token while it believes it
      * is still valid — which is exactly the situation after a 401 on a token the
      * provider has not yet noticed is dead. `refreshToken()` is the contract's
@@ -70,8 +91,13 @@ export declare class TokenAuthProvider implements IAuthProvider {
 export declare class SamlAuthProvider implements IAuthProvider {
     private readonly sessionCookies;
     readonly kind = "saml";
+    /** Nothing to get ready: this credential is complete as constructed. */
+    prepare(): Promise<void>;
+    /** No TLS material: this credential lives in a header, not in the transport. */
+    transportMaterial(): ICertificateMaterial;
     constructor(sessionCookies: string);
-    authorizationHeader(): Promise<string>;
+    /** Not a header: this credential authenticates with the cookies below. */
+    authorizationHeader(): Promise<string | null>;
     /** The cookies to present. */
     cookies(): string;
 }
@@ -86,10 +112,13 @@ export declare class CertificateAuthProvider implements IAuthProvider {
     private readonly loader;
     private readonly config;
     readonly kind = "certificate";
+    /** Not cookies. This one authenticates with a header. */
+    cookies(): string | null;
     private material;
     constructor(loader: ICertificateMaterialLoader, config: ISapConfig);
     prepare(): Promise<void>;
-    authorizationHeader(): Promise<string>;
-    httpsAgentOptions(): AgentOptions;
+    /** Not a header: this credential authenticates through TLS. */
+    authorizationHeader(): Promise<string | null>;
+    transportMaterial(): ICertificateMaterial;
 }
 //# sourceMappingURL=providers.d.ts.map