sap-ai-dev-toolkit 0.3.0 → 0.3.3

package/src/mcp-proxy.mjs

@@ -4,6 +4,7 @@ import { sanitizeChildEnv, slugifyDestination } from './bas-discovery.mjs';
 import { ABAP_LINT_TOOL, runABAPLint } from './abaplint.mjs';
 import { createEngineeringTools } from './engineering-tools.mjs';
 import { brandedEnvValue } from './branding.mjs';
+import { createBasDestinationRelay } from './bas-destination-relay.mjs';
 
 const JSONRPC = '2.0';
 const FORWARDED_METHODS = new Set(['ping', 'resources/list', 'resources/read', 'resources/templates/list', 'prompts/list', 'completion/complete', 'logging/setLevel']);
@@ -58,8 +59,27 @@ function closeDestinationRoute(destination) {
   return closedRoutes.get(destination);
 }
 
+function useBasDestinationRelay(destination, env = process.env) {
+  if (String(brandedEnvValue(env, 'DISABLE_BAS_RELAY') || '').toLowerCase() === 'true') return false;
+  if (destination.source === 'cloud-foundry') return false;
+  if (!destination.authentication) return false;
+  return Boolean(destination.url && String(destination.url).includes('.dest'));
+}
+
 function childEnvironment(destination, env) {
-  return { ...sanitizeChildEnv(env), ...(destination.childEnv || {}) };
+  const childEnv = { ...sanitizeChildEnv(env), ...(destination.childEnv || {}) };
+  // The VSP child must reach the local BAS relay directly, never through the
+  // BAS .dest proxy. Without a loopback exception every child request would
+  // be double-proxied and the relay's session pairing could never apply.
+  if (destination.relay) {
+    const loopback = '127.0.0.1,localhost';
+    for (const key of ['NO_PROXY', 'no_proxy']) {
+      const entries = String(childEnv[key] || '').split(',').map(value => value.trim()).filter(Boolean);
+      for (const host of loopback.split(',')) if (!entries.some(entry => entry.toLowerCase() === host)) entries.push(host);
+      childEnv[key] = entries.join(',');
+    }
+  }
+  return childEnv;
 }
 
 
@@ -95,12 +115,14 @@ class Child {
     this.process.on('error', error => {
       if (!this.closing && !this.pending.size && this.options.log) this.options.log(`[${destination.name}] VSP child process error: ${diagnosticText(error.message)}`);
       this.fail(error);
-      void closeDestinationRoute(destination);
+      // Relay routes survive child crashes so self-healing restarts can reuse
+      // them; they are closed by the proxy shutdown path instead.
+      if (!destination.relay) void closeDestinationRoute(destination);
     });
     this.process.on('exit', (code, signal) => {
       if (!this.closing && !this.pending.size && this.options.log) this.options.log(`[${destination.name}] VSP child exited (${code ?? signal})`);
       this.fail(new Error(`child exited (${code ?? signal})`));
-      void closeDestinationRoute(destination);
+      if (!destination.relay) void closeDestinationRoute(destination);
     });
   }
 
@@ -209,36 +231,87 @@ export class MCPProxy {
   start() {
     if (this.started) return this;
     this.started = true;
-    for (const destination of this.destinations) {
-      try {
-        this.log(`[${destination.name}] starting VSP child (client=${destination.client || '001'})`);
-        this.children.push({
-          destination,
-          child: new Child(this.binary, destination, {
-            env: this.env,
-            spawn: this.spawn,
-            args: this.childArgs?.(destination),
-            log: this.log,
-            onNotification: notification => {
-              if (this.clientInitialized) this.output(JSON.stringify(notification));
-              else this.pendingNotifications.push(notification);
-            }
-          })
-        });
-      } catch (error) {
-        this.log(`[${destination.name}] failed to start child: ${diagnosticText(error.message)}`);
-        void closeDestinationRoute(destination);
+    this.starting = (async () => {
+      for (const originalDestination of this.destinations) {
+        let destination = originalDestination;
+        try {
+          if (useBasDestinationRelay(originalDestination, this.env)) {
+            const relay = createBasDestinationRelay(originalDestination, { env: this.env, log: this.log });
+            const originalClose = originalDestination.close;
+            const relayUrl = await relay.ready;
+            destination = {
+              ...originalDestination,
+              url: relayUrl,
+              relay: true,
+              async close() {
+                await originalClose?.();
+                await relay.close();
+              }
+            };
+            this.log(`[${originalDestination.name}] BAS destination relay enabled (${relayUrl})`);
+          }
+          this.log(`[${destination.name}] starting VSP child (client=${destination.client || '001'})`);
+          this.children.push({
+            destination,
+            child: new Child(this.binary, destination, {
+              env: this.env,
+              spawn: this.spawn,
+              args: this.childArgs?.(destination),
+              log: this.log,
+              onNotification: notification => {
+                if (this.clientInitialized) this.output(JSON.stringify(notification));
+                else this.pendingNotifications.push(notification);
+              }
+            })
+          });
+        } catch (error) {
+          this.log(`[${destination.name}] failed to start child: ${diagnosticText(error.message)}`);
+          void closeDestinationRoute(destination);
+        }
       }
-    }
-    if (!this.children.length) {
-      this.started = false;
-      for (const destination of this.destinations) void closeDestinationRoute(destination);
-      throw new Error('No destination child could be started');
-    }
+      if (!this.children.length) {
+        this.started = false;
+        for (const destination of this.destinations) void closeDestinationRoute(destination);
+        throw new Error('No destination child could be started');
+      }
+      return this;
+    })();
+    // Mark the startup promise as handled here; initializeChildren re-awaits
+    // it so startup failures still surface as MCP initialization errors
+    // without triggering an unhandled rejection in between.
+    this.starting.catch(() => {});
     return this;
   }
 
+  // Self-healing mode 3: transparently restart a crashed VSP child so an
+  // MCP tools/call does not permanently fail after a single crash. The
+  // restarted child re-initializes and re-registers tools before the call
+  // is retried once.
+  async restartChild(entry) {
+    if (this.shuttingDown) throw new Error('MCP proxy is shutting down');
+    const name = entry.destination.name;
+    this.log(`[${name}] VSP child crashed; self-healing restart in progress`);
+    await entry.child.close().catch(() => {});
+    const child = new Child(this.binary, entry.destination, {
+      env: this.env,
+      spawn: this.spawn,
+      args: this.childArgs?.(entry.destination),
+      log: this.log,
+      onNotification: notification => {
+        if (this.clientInitialized) this.output(JSON.stringify(notification));
+        else this.pendingNotifications.push(notification);
+      }
+    });
+    entry.child = child;
+    entry.server = await child.initialize(this.lastInitializeParams || {});
+    await child.listTools().catch(() => {});
+    this.log(`[${name}] VSP child self-healing restart complete`);
+    return entry;
+  }
+
   async initializeChildren(params) {
+    await this.starting;
+    this.lastInitializeParams = params;
     const healthy = [];
     for (const entry of this.children) {
       this.log(`[${entry.destination.name}] initializing VSP MCP session`);
@@ -342,6 +415,19 @@ export class MCPProxy {
           return response.error ? { ...response, id: message.id } : rpcResult(message.id, response.result);
         } catch (error) {
           this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} failed after ${Date.now() - startedAt}ms: ${diagnosticText(error.rpcError?.message || error.message)}`);
+          // Self-healing: a dead child (crash, OOM, transient pipe break) is
+          // restarted and the call retried once before surfacing the error.
+          const childBroken = mapped.entry.child.exited || !mapped.entry.child.process.stdin.writable;
+          if (childBroken && !this.shuttingDown) {
+            try {
+              await this.restartChild(mapped.entry);
+              this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} retried after self-healing restart`);
+              const retried = await mapped.entry.child.request('tools/call', upstreamParams);
+              return retried.error ? { ...retried, id: message.id } : rpcResult(message.id, retried.result);
+            } catch (restartError) {
+              this.log(`[${mapped.entry.destination.name}] tools/call ${toolName} self-healing restart failed: ${diagnosticText(restartError.message)}`);
+            }
+          }
           return error.rpcError ? rpcError(message.id, error.rpcError.code || -32001, error.rpcError.message || error.message, error.rpcError.data) : rpcError(message.id, -32001, `Destination ${mapped.entry.destination.name} failed: ${error.message}`);
         }
       }
@@ -393,10 +479,12 @@ export class MCPProxy {
   async close() {
     if (this.shuttingDown) return;
     this.shuttingDown = true;
-    await Promise.all(this.destinations.map(async destination => {
-      const entry = this.children.find(candidate => candidate.destination === destination);
-      await entry?.child.close();
-      await closeDestinationRoute(destination);
+    const closed = new Set();
+    await Promise.all(this.children.map(async entry => {
+      await entry.child.close();
+      await closeDestinationRoute(entry.destination);
+      closed.add(entry.destination);
     }));
+    await Promise.all(this.destinations.filter(destination => !closed.has(destination)).map(destination => closeDestinationRoute(destination)));
   }
 }

package/src/setup.mjs

@@ -1,9 +1,10 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
-import { checkboxPrompt, colorText, formatStatus } from './terminal-ui.mjs';
+import { checkboxPrompt, colorText, formatStatus, textPrompt } from './terminal-ui.mjs';
 import { discoverDestinations, remediation } from './bas-discovery.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys } from './cf-destination.mjs';
 import { SAP_DEVELOPMENT_MCP_SERVERS, collectCloudFoundryKeyReferencesFromAllEntries, collectManagedCloudFoundryKeyReferences, installMcpConfig, readMcpConfig, resolveMcpConfigPath } from './mcp-config.mjs';
+import { readCredentials, removeDestinationCredentials, resolveCredentialsPath, storeDestinationCredentials } from './credentials-store.mjs';
 
 const SETUP_COMMAND = 'sap-ai-dev --setup';
 
@@ -23,6 +24,56 @@ async function confirmCloudFoundryImport({ input = stdin, output = stdout } = {}
   }
 }
 
+// Internet destinations reach SAP through the BAS .dest proxy, which strips
+// Set-Cookie and makes ADT CSRF-protected writes impossible. Ask once for
+// direct-connection credentials and store them next to the MCP config; the
+// relay then connects straight to the backend host with Basic auth.
+async function promptForInternetDestinationCredentials({ destinations, credentialsPath, existing = {}, input = stdin, output = stdout } = {}) {
+  const stored = {};
+  const internetDestinations = destinations.filter(destination =>
+    destination.source !== 'cloud-foundry'
+    && String(destination.proxyType || '').toLowerCase() === 'internet'
+    && /^basicauthentication$/i.test(String(destination.authentication || '')));
+  if (!internetDestinations.length) return stored;
+
+  print(output, '');
+  print(output, formatStatus('Some selected destinations are Internet type with basic authentication.', 'step', output, 'Direct connect'));
+  print(output, '  The BAS proxy strips SAP session cookies, which blocks ADT writes (CSRF validation).');
+  print(output, '  Providing a user and password enables a direct connection for those destinations.');
+  print(output, `  Credentials are stored beside your MCP config in ${credentialsPath} (never inside mcp.json).`);
+  print(output, '');
+
+  for (const destination of internetDestinations) {
+    const known = existing[destination.name];
+    if (known?.user && known?.password) {
+      print(output, formatStatus(`Credentials for ${destination.name} are already stored (user ${known.user}). Press Enter at both prompts to keep them.`, 'info', output, 'Direct connect'));
+    }
+    const userAnswer = await textPrompt({
+      message: colorText(`👤 ${destination.name} — SAP user`, 'cyan', output),
+      required: false,
+      placeholder: known ? `${known.user} (Enter keeps stored user)` : 'SAP user name'
+    }, { input, output });
+    const user = userAnswer.trim() || known?.user || '';
+    const passwordAnswer = await textPrompt({
+      message: colorText(`🔒 ${destination.name} — SAP password${known ? ' (Enter keeps stored password)' : ''}`, 'cyan', output),
+      secret: true,
+      required: false
+    }, { input, output });
+    const password = passwordAnswer || known?.password || '';
+    if (!user || !password) {
+      print(output, formatStatus(`No complete credentials for ${destination.name}; direct connect stays inactive for it.`, 'warning', output, 'Direct connect'));
+      continue;
+    }
+    stored[destination.name] = {
+      host: destination.backendUrl || known?.host || '',
+      user,
+      password
+    };
+    print(output, formatStatus(`Stored credentials for ${destination.name}.`, 'success', output, 'Direct connect'));
+  }
+  return stored;
+}
+
 function safeProbe(probe) {
   const result = {};
   if (typeof probe?.status === 'string') result.status = probe.status;
@@ -39,6 +90,8 @@ function safeBasDestination(destination) {
     url: destination.url,
     client: destination.client,
     authentication: destination.authentication,
+    proxyType: destination.proxyType,
+    backendUrl: destination.backendUrl || null,
     probe: safeProbe(destination.probe)
   };
 }
@@ -117,6 +170,7 @@ export async function runSetup({
   }
   const destinations = basDestinations.map(safeBasDestination);
   const warnings = [];
+  const credentialWarnings = [];
   let createdKeys = [];
   let configPath;
   let managedKeys = [];
@@ -228,6 +282,39 @@ export async function runSetup({
       shortcuts: { all: 'a' }
     }, { input, output });
   }
+
+  // Ask for direct-connect credentials for selected Internet destinations
+  // so ADT writes work despite the BAS proxy stripping session cookies.
+  const credentialsPath = await resolveCredentialsPath(env, configPath);
+  const internetSelected = selected.filter(destination =>
+    destination.source !== 'cloud-foundry'
+    && String(destination.proxyType || '').toLowerCase() === 'internet'
+    && /^basicauthentication$/i.test(String(destination.authentication || '')));
+  if (internetSelected.length) {
+    try {
+      const existingMap = (await readCredentials(credentialsPath).catch(() => ({ destinations: {} }))).destinations || {};
+      const storedNow = await promptForInternetDestinationCredentials({
+        destinations: selected,
+        credentialsPath,
+        existing: existingMap,
+        input,
+        output
+      });
+      for (const [name, entry] of Object.entries(storedNow)) {
+        await storeDestinationCredentials(credentialsPath, name, entry);
+      }
+      // Remove stored credentials for Internet destinations that are no
+      // longer selected, so the file only tracks active servers.
+      const stillSelected = new Set(selected.map(destination => destination.name));
+      const stale = Object.keys(existingMap)
+        .filter(name => !stillSelected.has(name))
+        .filter(name => internetSelected.every(destination => destination.name !== name));
+      if (stale.length) await removeDestinationCredentials(credentialsPath, stale);
+    } catch (error) {
+      if (/Prompt interrupted/.test(error.message)) throw error;
+      credentialWarnings.push(`Direct-connect credentials could not be stored: ${error.message}`);
+    }
+  }
   try {
     const result = await install(selected, { env, sapDevelopmentServers });
     const location = result?.path ? ` in ${result.path}` : '';
@@ -248,8 +335,9 @@ export async function runSetup({
       }
     }
     await reportWarnings(warnings);
+    await reportWarnings(credentialWarnings);
     await reportWarnings(cleanupWarnings);
-    return { selected, ...(result || {}), warnings: [...warnings, ...cleanupWarnings] };
+    return { selected, ...(result || {}), warnings: [...warnings, ...credentialWarnings, ...cleanupWarnings] };
   } catch (error) {
     const cleanupWarnings = [];
     if (createdKeys.length) {

package/src/terminal-ui.mjs

@@ -210,3 +210,87 @@ export async function checkboxPrompt({ message, choices, required = false, short
     }
   });
 }
+
+// Single-line text/secret prompt matching the checkbox prompt's interaction
+// style. Secrets are masked with ●, support backspace, and can be re-prompted
+// through `validate`. Ctrl+C rejects with 'Prompt interrupted'.
+export async function textPrompt({ message, secret = false, required = true, placeholder = '', validate } = {}, { input = process.stdin, output = process.stdout } = {}) {
+  let value = '';
+  let renderedLines = 0;
+  let done = false;
+  let previousRawMode;
+
+  const write = text => output.write(text);
+  const masked = () => '●'.repeat(value.length);
+  const clearRendered = () => {
+    if (!renderedLines) return;
+    write(`\u001b[${renderedLines}A\u001b[J`);
+    renderedLines = 0;
+  };
+  const render = (error = '') => {
+    const columns = Number.isFinite(output?.columns) ? output.columns : 80;
+    const lines = [];
+    const hint = secret ? ' (input is hidden)' : '';
+    lines.push(truncateToColumns(`${message}${hint}`, columns));
+    const shown = secret ? masked() : value;
+    const display = shown || colorText(placeholder, 'cyan', output);
+    lines.push(truncateToColumns(`❯ ${display}`, columns));
+    if (error) lines.push(colorText(`  ${error}`, 'red', output));
+    clearRendered();
+    write(`${lines.join('\n')}\n`);
+    renderedLines = lines.length;
+  };
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      input.off('keypress', onKeypress);
+      if (typeof input.setRawMode === 'function' && previousRawMode !== undefined) input.setRawMode(previousRawMode);
+      if (typeof input.pause === 'function') input.pause();
+      write('\u001b[?25h');
+    };
+    const finish = result => {
+      if (done) return;
+      done = true;
+      clearRendered();
+      const summary = secret ? '✓ saved' : (result || '(empty)');
+      write(`${stripAnsi(message)} ${summary}\n`);
+      cleanup();
+      resolve(result);
+    };
+    const fail = error => {
+      if (done) return;
+      done = true;
+      cleanup();
+      reject(error);
+    };
+    const onKeypress = (chunk, key = {}) => {
+      if (key.ctrl && key.name === 'c') return fail(new Error('Prompt interrupted'));
+      if (key.name === 'return' || key.name === 'enter') {
+        const validation = typeof validate === 'function' ? validate(value) : true;
+        if (validation !== true) return render(String(validation));
+        if (required && !value.length) return render('Enter a value (or press Ctrl+C to skip).');
+        return finish(value);
+      }
+      if (key.name === 'backspace' || key.name === 'delete') {
+        value = value.slice(0, -1);
+      } else if (key.sequence && !key.ctrl && !key.meta && /^.$/u.test(key.sequence)) {
+        value += key.sequence;
+      } else {
+        return;
+      }
+      render();
+    };
+
+    try {
+      readline.emitKeypressEvents(input);
+      previousRawMode = input.isRaw;
+      if (typeof input.setRawMode === 'function') input.setRawMode(true);
+      if (typeof input.resume === 'function') input.resume();
+      write('\u001b[?25l');
+      input.on('keypress', onKeypress);
+      render();
+    } catch (error) {
+      fail(error);
+    }
+  });
+}

package/test/bas-destination-relay.test.mjs

@@ -0,0 +1,188 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { request as httpRequest } from 'node:http';
+import { createBasDestinationRelay } from '../src/bas-destination-relay.mjs';
+
+const UNSAFE_METHODS = ['POST', 'PUT', 'PATCH', 'DELETE'];
+
+// Simulates SAP ADT semantics: a CSRF token is only valid when the unsafe
+// request carries BOTH the token and the session cookies that were set
+// together with it. This reproduces the 403 "CSRF token validation failed"
+// seen on the BAS .dest proxy path before the relay paired sessions.
+function sapLikeBackend({ neverAcceptUnsafe = false, rotateOnFetch = false } = {}) {
+  const state = { sessionCounter: 0, requests: [] };
+  const server = http.createServer((req, res) => {
+    state.requests.push({ method: req.method, path: req.url, headers: { ...req.headers } });
+    if (req.method === 'GET' && req.headers['x-csrf-token'] === 'Fetch') {
+      state.sessionCounter += 1;
+      res.writeHead(200, {
+        'x-csrf-token': `token-${state.sessionCounter}`,
+        'set-cookie': [`sap-session-${state.sessionCounter}=s${state.sessionCounter}; path=/`, 'sap-usercontext=sap-client=100; path=/']
+      });
+      res.end('<ok/>');
+      return;
+    }
+    if (UNSAFE_METHODS.includes(req.method)) {
+      if (neverAcceptUnsafe) {
+        res.writeHead(403, { 'x-csrf-token': 'Required' });
+        res.end('CSRF token validation failed');
+        return;
+      }
+      const token = req.headers['x-csrf-token'];
+      const cookie = String(req.headers.cookie || '');
+      const match = String(token || '').match(/^token-(\d+)$/);
+      // Without rotation any still-live token+cookie pair is accepted; with
+      // rotation only the newest issued session remains valid, matching SAP
+      // server-side session invalidation.
+      const valid = match && cookie.includes(`sap-session-${match[1]}=`) && (!rotateOnFetch || Number(match[1]) === state.sessionCounter);
+      if (!valid) {
+        res.writeHead(403, { 'x-csrf-token': 'Required' });
+        res.end('CSRF token validation failed');
+        return;
+      }
+      res.writeHead(201);
+      res.end('<created/>');
+      return;
+    }
+    res.writeHead(200);
+    res.end('<read/>');
+  });
+  return { state, server };
+}
+
+async function startServer(server) {
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  return server.address().port;
+}
+
+function relayFetch(relayUrl, path, options = {}) {
+  const target = new URL(path, relayUrl);
+  return new Promise((resolve, reject) => {
+    const req = httpRequest(target, { method: options.method || 'GET', headers: options.headers || {} }, response => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', chunk => { body += chunk; });
+      response.on('end', () => resolve({ status: response.statusCode, headers: response.headers, body }));
+    });
+    req.on('error', reject);
+    if (options.body) req.write(options.body);
+    req.end();
+  });
+}
+
+async function withBackend(options, handler) {
+  const { state, server } = sapLikeBackend(options || {});
+  const backendPort = await startServer(server);
+  const logs = [];
+  const relay = createBasDestinationRelay(
+    { name: 'TEST', url: `http://127.0.0.1:${backendPort}`, authentication: 'BasicAuthentication' },
+    {
+      env: { HTTP_PROXY: '' },
+      fetchImpl: options?.fetchImpl || ((url, init) => globalThis.fetch(url, init)),
+      log: message => logs.push(message)
+    }
+  );
+  const relayUrl = await relay.ready;
+  try {
+    return await handler({ state, relay, relayUrl, logs });
+  } finally {
+    await relay.close();
+    await new Promise(resolve => server.close(resolve));
+  }
+}
+
+test('pairs CSRF token with its session cookies so unsafe requests succeed', async () => {
+  await withBackend(null, async ({ relayUrl, state }) => {
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', headers: { accept: 'application/xml' }, body: '<x/>' });
+    assert.equal(response.status, 201, `expected 201, got ${response.status}: ${response.body}`);
+    const post = state.requests.find(request => request.method === 'POST');
+    assert.match(post.headers['x-csrf-token'], /^token-\d+$/);
+    assert.match(String(post.headers.cookie), /sap-session-\d+=/);
+  });
+});
+
+test('reuses the cached CSRF session for subsequent unsafe requests', async () => {
+  await withBackend(null, async ({ relay, relayUrl, state }) => {
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<y/>' });
+    const fetches = state.requests.filter(request => request.headers['x-csrf-token'] === 'Fetch');
+    assert.equal(fetches.length, 1, 'second POST must reuse the cached session');
+    assert.equal(state.requests.filter(request => request.method === 'POST').length, 2);
+    assert.equal(relay.stats.csrfFetches, 1);
+    assert.equal(relay.stats.csrfRetries, 0);
+  });
+});
+
+test('self-heals when SAP rotates the session: refetches token and cookies', async () => {
+  await withBackend({ rotateOnFetch: true }, async ({ relay, relayUrl, state }) => {
+    // A first POST establishes session token-1. SAP then invalidates it
+    // server-side (simulated by the rotation rule below).
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    state.sessionCounter += 1;
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<y/>' });
+    assert.equal(response.status, 201, `rotated session must heal via refetch, got ${response.status}`);
+    assert.ok(relay.stats.csrfRetries >= 1, 'a retry must have been counted');
+    const fetches = state.requests.filter(request => request.headers['x-csrf-token'] === 'Fetch');
+    assert.ok(fetches.length >= 2, 'a fresh token fetch must have occurred');
+  });
+});
+
+test('stops retrying after bounded attempts and surfaces the failure', async () => {
+  await withBackend({ neverAcceptUnsafe: true }, async ({ relay, relayUrl, state }) => {
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    assert.equal(response.status, 403);
+    const attempts = state.requests.filter(request => UNSAFE_METHODS.includes(request.method));
+    assert.equal(attempts.length, 1 + 3, 'one initial try plus three bounded retries');
+    assert.equal(relay.stats.csrfRetries, 3);
+  });
+});
+
+test('GET requests pass through without CSRF handling', async () => {
+  await withBackend(null, async ({ relayUrl, state, relay }) => {
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/discovery', { headers: { accept: 'application/xml' } });
+    assert.equal(response.status, 200);
+    assert.equal(state.requests.filter(request => request.headers['x-csrf-token']).length, 0);
+    assert.equal(relay.stats.csrfFetches, 0);
+  });
+});
+
+test('drops POST body headers from the token-fetch GET', async () => {
+  await withBackend(null, async ({ relayUrl, state }) => {
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', {
+      method: 'POST',
+      headers: { accept: 'application/xml', 'content-type': 'application/xml', 'content-length': '5' },
+      body: '<xy/>'
+    });
+    const fetchRequest = state.requests.find(request => request.headers['x-csrf-token'] === 'Fetch');
+    assert.equal(fetchRequest.headers['content-type'], undefined, 'content-type must not leak into token GET');
+    assert.equal(fetchRequest.headers['content-length'], undefined, 'content-length must not leak into token GET');
+  });
+});
+
+test('falls back to a proxy tunnel when the absolute-form request is refused', async () => {
+  const fetchCalls = [];
+  const fetchImpl = (url, options = {}) => {
+    fetchCalls.push({ url: String(url), tunneled: Boolean(options.dispatcher && options.dispatcher.proxyTunnel !== false && options.dispatcher.constructor?.name === 'ProxyAgent' && options.dispatcher.__tunnelMarker !== false) });
+    // First call (absolute-form through proxy) is refused by the proxy itself.
+    if (fetchCalls.length === 1) return Promise.resolve(new Response('<gateway/>', { status: 502 }));
+    return Promise.resolve(new Response('<ok/>', { status: 200, headers: { 'x-csrf-token': 'tok' } }));
+  };
+  const { state, server } = sapLikeBackend();
+  void state;
+  const backendPort = await startServer(server);
+  const relay = createBasDestinationRelay(
+    { name: 'TEST', url: `http://127.0.0.1:${backendPort}`, authentication: 'BasicAuthentication' },
+    { env: { HTTP_PROXY: 'http://127.0.0.1:1' }, fetchImpl, log: () => {} }
+  );
+  const relayUrl = await relay.ready;
+  try {
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/discovery');
+    assert.equal(response.status, 200);
+    assert.equal(relay.stats.tunnelFallbacks, 1, 'exactly one tunnel fallback must occur');
+    assert.equal(fetchCalls.length, 2, 'absolute-form attempt then one tunnel retry');
+  } finally {
+    await relay.close();
+    await new Promise(resolve => server.close(resolve));
+  }
+});