arena-plm-fiori/tools/adt-reentrance-login/README.md

# adt-reentrance-login

Capture an SAP **ADT reentrance ticket** through a **localhost redirect**, so
`abap-adt-mcp` can log on to the S/4HANA Cloud development tenant from this
headless / SSH-only host — without a browser window on the server's desktop.

Node 24, standard library only, no dependencies, no install step.

---

## Why this exists

`abap-adt-mcp` 2.1.0 can do browser SSO, but only by launching a **server-side**
Chrome window (`headless: false`) and harvesting cookies over the DevTools
protocol; there is no localhost redirect in that path, so over multi-hop SSH
neither the desktop nor a DevTools relay is reachable in practice
[KNOWLEDGE.md, 2026-09-16].

ADT for VS Code does it differently. It opens

```
https://<tenant>/sap/bc/adt/core/http/reentranceticket?redirect-url=http://localhost:<port>/adt/redirect
```

and reads the ticket back out of the redirect

```
http://localhost:<port>/adt/redirect?...&reentrance-ticket=<ticket>
```

(observed 2026-09-16). That half is portable: **your** browser does the SSO, the
tenant redirects to `localhost`, and a forwarded TCP port puts "localhost" back
on this host. This script is that listener.

---

## Run it

Three steps, three terminals-worth of context. Values below use the defaults
(tenant `my431353`, port `42010`, 300 s timeout).

### 1. Start the helper on this host

```bash
node /home/alexz/projects/sap-integrations-mcl/arena-plm/tools/adt-reentrance-login/login.mjs
```

It prints (to stderr) the port to forward and the URL to open, then waits up to
300 seconds for exactly one redirect.

### 2. Forward the port to the machine running your browser

**VS Code:** open the **Ports** panel (`Ctrl+Shift+P` → *Ports: Focus on Ports
View*) → **Forward a Port** → enter `42010`. VS Code forwards it to your local
`localhost:42010`.

**Plain SSH**, from your laptop:

```bash
ssh -L 42010:127.0.0.1:42010 <this-host>
```

The browser must reach **this host's** localhost. Without the forward the tenant
redirects your browser to its own machine and nothing is captured.

### 3. Open the URL in that browser and complete SSO

```
https://my431353.s4hana.cloud.sap/sap/bc/adt/core/http/reentranceticket?redirect-url=http://localhost:42010/adt/redirect
```

(Or capture it programmatically: `node login.mjs --print-url-only`.)

After SSO the tab lands on "Ticket captured", the helper writes
`~/.abap-adt-mcp/ticket.json` (mode 0600) and exits 0.

### 4. Make the MCP server pick it up

`~/.abap-adt-mcp/ticket-provider.sh` already `cat`s that file, and
`abap-adt-mcp` caches the login per destination — it only re-runs the provider
on an explicit `login` call or a `reauthenticate`
(`dist/index.js:268-292`, `615-625`, read 2026-09-18). So after capturing a
fresh ticket, call the MCP `login` tool for the destination.

---

## Options

| Flag | Default | Meaning |
|---|---|---|
| `--tenant <url>` | `https://my431353.s4hana.cloud.sap` | Tenant base URL. The UI host, not the `-api` host. |
| `--port <n>` | `42010` | Loopback port. Bound to `127.0.0.1` **only**; there is no flag to change the bind address. |
| `--timeout <seconds>` | `300` | Give up and write nothing. |
| `--out <path>` | `~/.abap-adt-mcp/ticket.json` | Output file, mode 0600 (directory created 0700). |
| `--client <nnn>` | *not sent* | Adds `sap-client=<nnn>`. See "Which client?" below. |
| `--allow-host <name>` | — | Additionally accept this `Host` header (repeatable), for tunnelled forwards that are not `localhost`. |
| `--probe` | off | After capture, test cookie vs header transport (below). |
| `--print-url-only` | off | Print the logon URL to **stdout** and exit; start no listener. |
| `--help` | — | Usage. |

Exit codes: `0` captured · `2` usage · `3` timeout · `4` cannot bind · `5`
redirect arrived without a usable ticket.

### Which client?

Nothing is hard-coded. The client the browser session uses is unconfirmed; the
published service URL shows `sap-client=080`, but that is the API host's
service URL, not proof about the UI logon. Run without `--client` first; only
add `--client 080` if the tenant needs it.

---

## Probe mode (`--probe`)

Open question this settles: SAP documents a **logon ticket** in the `MYSAPSSO2`
**cookie** and an **assertion ticket** in a `mysapsso2` **header**
[source: sap-docs sap-help loio 3354605668 and 3361378221, verified
2026-09-18]. Which one a *reentrance* ticket behaves as is **unknown**, and it
decides whether `abap-adt-mcp`'s `sso2` mode can work at all — that mode sends
the value strictly as a **cookie** (`dist/lib/sso2TicketProvider.js`, read
2026-09-18).

With `--probe`, after capture the helper makes two GETs to
`<tenant>/sap/bc/adt/core/discovery` with `Accept: application/atomsvc+xml` and
**no other credentials**:

- **(a)** `Cookie: MYSAPSSO2=<ticket>`
- **(b)** `MYSAPSSO2: <ticket>`

and reports only the HTTP status of each, whether a `set-cookie` with
`SAP_SESSIONID` came back, and which succeeded. Bodies are discarded unread. A
redirect is reported by **host only** (a SAML `Location` can carry request
material).

Read the verdict as:

- **cookie worked** → `abap-adt-mcp`'s `sso2` mode works as-is.
- **only the header worked** → `sso2` mode **cannot** use this ticket; the MCP
  server would need a header transport it does not have.
- **neither** → expired ticket, wrong client, or wrong mechanism entirely.

---

## Ticket lifetime

- **The lifetime of a reentrance ticket is not verified here.** Treat it as
  short-lived and re-run the helper whenever logon fails. Do not assume the
  8-hour default of a classic SAP logon ticket applies.
- Whether a reentrance ticket is **single-use** is also unverified. If a
  captured ticket authenticates once and then stops, assume single-use and
  re-capture.
- Expiry surfaces in the ADT MCP only as **"Your user was logged off."**
  `abap_list_destinations` and `get_object_type_details` still answer, so
  neither proves a live session; `abap_creation-run_validation` is the cheapest
  read-only liveness check [KNOWLEDGE.md, 2026-09-16].

---

## Security rules

These are contracts, not preferences. The ticket is a **live logon credential**
for the tenant.

1. **The ticket is never printed, logged, or put in an error message, argv, or
   an environment variable.** The only place it is written is `--out`, mode
   0600. Validation failures report the *reason* and the parameter *names*
   present — never values, never offending characters or positions.
2. **stdout stays empty.** Every human-readable message goes to stderr, so
   nothing sensitive can be captured by a `$(...)` around the helper. The single
   exception is `--print-url-only`, which prints the (secret-free) logon URL.
3. **The listener binds `127.0.0.1` only** and is one-shot. There is no flag to
   bind a wider interface. A `Host` header that is not a loopback name is
   refused (cheap DNS-rebinding guard); allow a specific tunnel name with
   `--allow-host`.
4. **Never paste the redirect URL** into a chat, issue, log, or file — it
   contains the ticket. Note that the URL also lands in **your browser's
   history**; clear it on a shared machine.
5. The output file is written with permissions set **before** any ticket byte
   reaches the disk (`open` + `fchmod` + `write`), so a pre-existing
   world-readable file cannot briefly expose it.
6. Ticket values are validated against the RFC 6265 cookie-octet set copied
   verbatim from `abap-adt-mcp` — a ticket the MCP server would reject is
   rejected here instead of being written to a file that cannot work.

### Percent-decoding, and why not `URLSearchParams`

The ticket is URL-decoded **exactly once** with `decodeURIComponent` over the
raw query pair, and never re-encoded.

`URLSearchParams` is deliberately **not** used: it applies
`application/x-www-form-urlencoded` rules and turns a literal `+` into a space.
Measured on Node v24.15.0, 2026-09-18:

```
'?reentrance-ticket=AB%2BCD+EF%3d'
  searchParams.get(...)            -> 'AB+CD EF='      <-- space, corrupt
  decodeURIComponent(raw pair)     -> 'AB+CD+EF='      <-- correct
```

A space is not a legal cookie-octet, so a base64 ticket carrying `+` would be
silently corrupted and then rejected.

---

## Configuration (handled by the repo owner, documented here for reference)

This script does **not** touch `~/.abap-adt-mcp/systems.json` or `.mcp.json`.
For the record, `abap-adt-mcp` 2.1.0 requires for `authType: "sso2"`
(`dist/lib/systems.js:73-149`, read 2026-09-18):

- `sso2.command` must be an **absolute executable path** (`sso2.args` optional,
  `sso2.timeoutMs` 1000–300000);
- the system `url` must be **HTTPS** ("so the ticket is never sent in
  plaintext");
- `insecureTls` is refused in combination with `sso2`;
- `authType: "ticket"` is accepted as an alias for `sso2`;
- the server warns at startup that every remote caller of an `sso2` destination
  shares the SAP identity of the user running it — one server instance per
  person.

---

## Troubleshooting

| Symptom | Cause |
|---|---|
| Browser cannot reach `localhost:42010` | Port not forwarded, or forwarded to the wrong host. Re-check step 2. |
| `port ... is already in use` (exit 4) | Another listener. Use `--port <n>` and forward **that** port. |
| `Timed out ... Nothing was written.` (exit 3) | SSO never completed, or the redirect went to the wrong machine. |
| `the redirect carried no reentrance-ticket parameter` (exit 5) | The tenant redirected without a ticket — usually a failed or cancelled SSO. The parameter names it *did* send are listed. |
| `ticket contains characters outside the RFC 6265 cookie-octet set` (exit 5) | The value is not usable as a `MYSAPSSO2` cookie; `abap-adt-mcp` would reject it too. |
| `Refused a redirect with Host: ...` | Forward is not a plain localhost forward. Re-run with `--allow-host <that-host>`. |