@cspeach/cli 1.1.21 → 1.1.23

package/dist/sap-link/registry.js

@@ -0,0 +1,259 @@
+// cspeach-cli/src/sap-link/registry.ts
+/**
+ * CAP phase 2 — the SAP link registry (Task 8). One in-process link per CAP
+ * project. The link and its UpstreamSession live side by side, so stopping a
+ * link also drops the pooled authenticated sockets, the cookie jar and the
+ * CSRF token (UpstreamSession.close()).
+ *
+ * Security rules held here:
+ *   - Never prompt for a password: the keychain lookup runs headless; a miss is
+ *     a fast plain error.
+ *   - TLS posture comes only from resolveSapTls(sys). A CA path is read and
+ *     trusted; an alias the user already marked insecure is reported loudly.
+ *     No new insecure path is introduced.
+ *   - Every error thrown from here is a SapLinkError (or the project's
+ *     LinkConfigError) with a fixed plain message. Raw keychain / fs / TLS text
+ *     never passes through.
+ *   - All links are closed when the process exits (best effort, installed once).
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadConfig as realLoadConfig, resolveSapTls } from '../config/loader.js';
+import { resolveSapPassword } from '../sap/connection-manager.js';
+import { readLinkTargets } from './project.js';
+import { startSapLink, SapLinkStartError } from './server.js';
+import { UpstreamSession } from './upstream.js';
+import { registerShutdownHook } from '../lib/shutdown-hooks.js';
+/** A registry error. Its message is always a fixed, plain, secret-free sentence. */
+export class SapLinkError extends Error {
+}
+const links = new Map();
+/** Registry key: the resolved path, lower-cased on Windows (case-insensitive file system). */
+function key(dir) {
+    const abs = path.resolve(dir);
+    return process.platform === 'win32' ? abs.toLowerCase() : abs;
+}
+export function writeLogFileFor(projectDir) {
+    const id = createHash('sha1').update(key(projectDir)).digest('hex').slice(0, 12);
+    return path.join(os.homedir(), '.cspeach', 'sap-link', id, 'write-log.jsonl');
+}
+export function findSapLink(projectDir) {
+    return links.get(key(projectDir))?.handle;
+}
+export function listSapLinks() {
+    return [...links.values()].map((e) => ({ projectDir: e.projectDir, url: e.handle.url, alias: e.alias }));
+}
+/** Same wording as server.ts's port-taken error, so the developer sees one message. */
+function portTakenMessage(port) {
+    return `Port ${port} is in use. Stop the program using it, or change the port in package.json ([s4] credentials.url) and start the SAP link again.`;
+}
+export function roleNoteFor(alias, role) {
+    return role === 'dev' ? undefined : `Writes are blocked: ${alias} has no role dev (reads only).`;
+}
+function httpNoteFor(alias, sys) {
+    return sys.useSsl
+        ? undefined
+        : `HTTPS is off for ${alias}. Your SAP login crosses the network unencrypted. Turn on HTTPS (useSsl) for this system.`;
+}
+/** Everything that shapes the upstream connection. A change means a restart, never a reuse. */
+function fingerprintFor(sys) {
+    const tls = resolveSapTls(sys);
+    return JSON.stringify([sys.host, sys.port, sys.client, sys.username, sys.authType, sys.useSsl === true, tls.mode, tls.caCertPath ?? '']);
+}
+function postureNotesFor(alias, sys) {
+    const tlsNote = tlsNoteFor(alias, sys);
+    const httpNote = httpNoteFor(alias, sys);
+    return { ...(tlsNote ? { tlsNote } : {}), ...(httpNote ? { httpNote } : {}) };
+}
+function tlsNoteFor(alias, sys) {
+    return resolveSapTls(sys).mode === 'insecure'
+        ? `TLS verification is OFF for ${alias} (insecure in config). Set sap.${alias}.ca_cert_path instead.`
+        : undefined;
+}
+function baseUrlFor(sys) {
+    const host = sys.host.includes(':') && !sys.host.startsWith('[') ? `[${sys.host}]` : sys.host;
+    return `${sys.useSsl ? 'https' : 'http'}://${host}:${sys.port}`;
+}
+// One registry operation at a time: two starts for one project must not race.
+let chain = Promise.resolve();
+function serial(fn) {
+    const run = chain.then(fn, fn);
+    chain = run.catch(() => undefined);
+    return run;
+}
+async function closeEntry(e) {
+    try {
+        e.upstream.close();
+    }
+    catch { /* best effort */ }
+    try {
+        await e.handle.close();
+    }
+    catch { /* best effort */ }
+}
+async function stopUnlocked(projectDir) {
+    const k = key(projectDir);
+    const e = links.get(k);
+    if (!e)
+        return false;
+    links.delete(k);
+    await closeEntry(e);
+    return true;
+}
+const sameList = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+export function ensureSapLink(projectDir, alias, partial = {}) {
+    return serial(() => ensureUnlocked(projectDir, alias, partial));
+}
+async function ensureUnlocked(projectDir, alias, partial) {
+    const deps = {
+        loadConfig: realLoadConfig,
+        // Never prompt (spec §6.3, same rule as the Fiori preview): a missing keychain entry is a fast error.
+        password: (a, s) => resolveSapPassword(a, s, { headless: () => true }),
+        readCa: (p) => readFileSync(p),
+        start: startSapLink,
+        ...partial,
+    };
+    // package.json first: its errors are plain LinkConfigErrors and need no SAP settings.
+    const targets = await readLinkTargets(projectDir);
+    const services = targets.services.map((s) => s.name);
+    const prefixes = targets.services.map((s) => s.prefix);
+    let cfg;
+    try {
+        cfg = await deps.loadConfig();
+    }
+    catch {
+        throw new SapLinkError('Could not read the SAP system settings.');
+    }
+    const k = key(projectDir);
+    const sys = cfg.sap?.[alias];
+    if (!sys) {
+        // The alias is gone from config: a link still running on it goes too.
+        if (links.get(k)?.alias === alias)
+            await stopUnlocked(projectDir);
+        throw new SapLinkError(`No SAP system named ${alias}. Add it with: cspeach config add-sap`);
+    }
+    const roleNote = roleNoteFor(alias, sys.role);
+    const fingerprint = fingerprintFor(sys);
+    const existing = links.get(k);
+    if (existing && existing.alias === alias && existing.fingerprint === fingerprint &&
+        existing.requestedPort === targets.port && sameList(existing.prefixes, prefixes) &&
+        // A link whose upstream got a 401 refuses every send: start means restart (new session, new password).
+        !existing.upstream.isLoginRejected()) {
+        // TLS/http notes describe the running link; the role is read fresh (the server does too).
+        return { handle: existing.handle, reused: true, services, ...existing.postureNotes, ...(roleNote ? { roleNote } : {}) };
+    }
+    // Another alias, connection, auth type, TLS posture, port or service list, or a rejected login: the old link goes first.
+    if (existing)
+        await stopUnlocked(projectDir);
+    if (targets.port !== 0) {
+        for (const [otherKey, other] of links) {
+            if (otherKey !== k && other.handle.listenPort === targets.port)
+                throw new SapLinkError(portTakenMessage(targets.port));
+        }
+    }
+    if (sys.authType !== 'basic')
+        throw new SapLinkError(`The SAP link needs password login. ${alias} uses a certificate.`);
+    let password;
+    try {
+        password = await deps.password(alias, sys);
+    }
+    catch {
+        throw new SapLinkError(`No stored password for ${alias}. Store it with: cspeach config add-sap`);
+    }
+    if (!password)
+        throw new SapLinkError(`No stored password for ${alias}. Store it with: cspeach config add-sap`);
+    const tls = resolveSapTls(sys);
+    let ca;
+    if (tls.caCertPath) {
+        try {
+            ca = deps.readCa(tls.caCertPath);
+        }
+        catch {
+            throw new SapLinkError(`Could not read the CA certificate for ${alias}. Check ca_cert_path in your config.`);
+        }
+    }
+    let upstream;
+    try {
+        upstream = new UpstreamSession({
+            baseUrl: baseUrlFor(sys),
+            client: sys.client,
+            username: sys.username,
+            password,
+            ...(ca ? { ca } : {}),
+            rejectUnauthorized: !tls.insecureSkipTlsVerify,
+        });
+    }
+    catch {
+        throw new SapLinkError(`The SAP settings for ${alias} are not valid. Check host and port.`);
+    }
+    let handle;
+    try {
+        handle = await deps.start({
+            alias, host: sys.host, port: sys.port,
+            listenPort: targets.port,
+            allowedPrefixes: prefixes,
+            // Fresh per request (Review Focus 3): a role change in config applies at once.
+            getRole: async () => (await deps.loadConfig()).sap?.[alias]?.role,
+            upstream,
+            secret: { password, username: sys.username },
+            writeLogFile: writeLogFileFor(projectDir),
+        });
+    }
+    catch (e) {
+        try {
+            upstream.close();
+        }
+        catch { /* best effort */ }
+        if (e instanceof SapLinkStartError && e.code === 'port-taken')
+            throw new SapLinkError(portTakenMessage(targets.port));
+        throw new SapLinkError('The SAP link could not start.');
+    }
+    const postureNotes = postureNotesFor(alias, sys);
+    links.set(k, { projectDir: path.resolve(projectDir), alias, prefixes, requestedPort: targets.port, fingerprint, postureNotes, handle, upstream });
+    installSapLinkExitHandler();
+    return { handle, reused: false, services, ...postureNotes, ...(roleNote ? { roleNote } : {}) };
+}
+export function stopSapLink(projectDir) {
+    return serial(() => stopUnlocked(projectDir));
+}
+export function __resetSapLinksForTests() {
+    return serial(async () => {
+        for (const k of [...links.keys()]) {
+            const e = links.get(k);
+            links.delete(k);
+            await closeEntry(e);
+        }
+    });
+}
+// ── Process exit ────────────────────────────────────────────────────────────
+let exitHandlerInstalled = false;
+/** Synchronous best effort: drop upstream sessions and stop listening. */
+function closeAllSapLinksSync() {
+    for (const e of links.values()) {
+        try {
+            e.upstream.close();
+        }
+        catch { /* best effort */ }
+        try {
+            void e.handle.close().catch(() => undefined);
+        }
+        catch { /* best effort */ }
+    }
+    links.clear();
+}
+/** Close every SAP link on CLI exit or a terminating signal. Idempotent. */
+export function installSapLinkExitHandler() {
+    if (exitHandlerInstalled)
+        return;
+    exitHandlerInstalled = true;
+    // The shared handler (lib/shutdown-hooks.ts) runs this on exit and on
+    // SIGINT/SIGTERM/SIGHUP, alongside the preview registry's cleanup, and
+    // re-raises the signal when nothing else is waiting for it.
+    registerShutdownHook(closeAllSapLinksSync);
+}
+/** Test-only — observe whether installSapLinkExitHandler has fired. */
+export function __isSapLinkExitHandlerInstalledForTests() {
+    return exitHandlerInstalled;
+}

package/dist/sap-link/server.js

@@ -0,0 +1,351 @@
+// cspeach-cli/src/sap-link/server.ts
+/**
+ * CAP phase 2 — the SAP link (spec §6.3): a loopback forwarder INSIDE the CSPeach
+ * process. The generated app's [s4] profile points at it; it adds the keychain
+ * login (UpstreamSession), refuses anything outside the imported services, and
+ * passes writes only while the alias role is exactly 'dev' — read fresh per
+ * request, so a config change takes effect at once.
+ *
+ * Hardening choices (Task 7, ruling R1 + review carry-overs):
+ *   - Browser / DNS-rebinding defence, checked BEFORE the role, the policy and the body:
+ *     exactly one Host header, equal to 127.0.0.1:<listenPort> or localhost:<listenPort>
+ *     (case-insensitive); an Origin header (if any) must be http://127.0.0.1[:port] or
+ *     http://localhost[:port] (`null` refused); Sec-Fetch-Site (if any) must be
+ *     same-origin or none. CAP's server-side calls send none of these browser headers.
+ *   - Request body capped at 10 MiB: a larger content-length is refused up front, a
+ *     streamed body is dropped the moment it passes the cap (413, connection closed).
+ *   - Only the policy's output is forwarded (method, normalised path, service prefix,
+ *     write flag), never req.method / req.url. GET and HEAD never carry a body upstream.
+ *   - The role is read fresh on every request. If it cannot be read: 503, nothing sent.
+ *   - Errors are mapped to fixed plain messages. No error text, stack, header or body
+ *     from upstream ever reaches the app. Upstream 401 → the login message; after it the
+ *     upstream refuses every send (ELOGINREJECTED) until the link restarts, same message.
+ *   - Write log: time, method, path without query, status. A failed log append does not
+ *     break the response (the write already happened upstream).
+ *   - Server timeouts are set; close() drops all connections and is idempotent.
+ *   - Nothing here logs requests, bodies, headers or the password.
+ *
+ * Fix round 1 (security review):
+ *   - R16: a write whose upstream call throws is still logged, with status 0
+ *     ("outcome unknown"): SAP may already have applied it.
+ *   - For a write the role is read AGAIN after the body arrives; anything but exactly
+ *     'dev' is a 403, so a role flip during a slow upload still stops the write.
+ *   - getRole() is raced against a timeout (5 s default, `roleTimeoutMs`); on timeout 503.
+ *   - Every answer carries `X-Content-Type-Options: nosniff`; pass-through answers also
+ *     carry `Content-Security-Policy: sandbox; default-src 'none'` (upstream values for
+ *     both are replaced), so SAP HTML can never run as a page on this origin.
+ *   - Only upstream statuses 200-599 are passed through; anything else is the generic 502.
+ *   - plain() resets statusMessage and any half-set headers, so a fallback 502 after a
+ *     failed pass-through never says "OK".
+ */
+import * as http from 'node:http';
+import { decideRequest, writesBlockedMessage } from './policy.js';
+import { appendWriteRow } from './write-log.js';
+export class SapLinkStartError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const REACH_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH', 'ECONNRESET', 'EAI_AGAIN']);
+export const MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024;
+const DISCARD_BUDGET_BYTES = 4 * 1024 * 1024;
+const DISCARD_GRACE_MS = 2_000;
+const HEADERS_TIMEOUT_MS = 30_000;
+const REQUEST_TIMEOUT_MS = 120_000;
+const DEFAULT_ROLE_TIMEOUT_MS = 5_000;
+const LOOPBACK_ORIGIN = /^http:\/\/(127\.0\.0\.1|localhost)(:\d{1,5})?$/i;
+/** Framing headers we set ourselves; never copied from the upstream answer. */
+const FRAMING_OUT = new Set(['content-length', 'transfer-encoding', 'connection', 'keep-alive']);
+/** Security headers we set ourselves on pass-through answers; upstream values are replaced. */
+const OWN_OUT = new Set(['x-content-type-options', 'content-security-policy']);
+const SETTINGS_UNREADABLE = 'Could not read the SAP system settings.';
+class RoleUnavailable extends Error {
+}
+/** getRole() with a deadline. Any throw or timeout becomes RoleUnavailable. */
+async function readRole(getRole, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(getRole),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new RoleUnavailable()), timeoutMs); }),
+        ]);
+    }
+    catch {
+        throw new RoleUnavailable();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function reachMessage(alias, host, port) {
+    return `Can't reach ${alias} (${host}:${port}) from this machine. Check network access to the SAP system.`;
+}
+class BodyTooLarge extends Error {
+}
+class BodyAborted extends Error {
+}
+function plain(res, status, text, close = false) {
+    if (res.headersSent) {
+        res.destroy();
+        return;
+    }
+    // A failed pass-through writeHead may have left a status text ("OK") or headers behind.
+    for (const name of res.getHeaderNames())
+        res.removeHeader(name);
+    res.statusMessage = http.STATUS_CODES[status] ?? 'Error';
+    const headers = {
+        'content-type': 'text/plain; charset=utf-8',
+        'content-length': Buffer.byteLength(text),
+        'x-content-type-options': 'nosniff',
+    };
+    if (close)
+        headers.connection = 'close';
+    res.writeHead(status, res.statusMessage, headers);
+    res.end(text);
+}
+/** All values of one header from rawHeaders (case-insensitive), duplicates kept. */
+function rawValues(req, name) {
+    const out = [];
+    for (let i = 0; i + 1 < req.rawHeaders.length; i += 2) {
+        if (req.rawHeaders[i].toLowerCase() === name)
+            out.push(req.rawHeaders[i + 1]);
+    }
+    return out;
+}
+/** R1: null when the request may go on, else the refusal. */
+function browserGuard(req, listenPort) {
+    const hosts = rawValues(req, 'host');
+    const want = [`127.0.0.1:${listenPort}`, `localhost:${listenPort}`];
+    if (hosts.length !== 1 || !want.includes(hosts[0].trim().toLowerCase())) {
+        return { status: 403, message: `The SAP link only answers requests addressed to 127.0.0.1:${listenPort}.` };
+    }
+    const origins = rawValues(req, 'origin');
+    if (origins.length > 1 || (origins.length === 1 && !LOOPBACK_ORIGIN.test(origins[0].trim()))) {
+        return { status: 403, message: 'The SAP link does not answer browser requests from other sites.' };
+    }
+    const sites = rawValues(req, 'sec-fetch-site');
+    if (sites.length > 1 || (sites.length === 1 && !['same-origin', 'none'].includes(sites[0].trim().toLowerCase()))) {
+        return { status: 403, message: 'The SAP link does not answer browser requests from other sites.' };
+    }
+    return null;
+}
+/** Reads the body up to `limit` bytes. Past the limit it stops reading and rejects. */
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let done = false;
+        const finish = (err) => {
+            if (done)
+                return;
+            done = true;
+            req.off('data', onData);
+            req.off('end', onEnd);
+            req.off('error', onError);
+            req.off('close', onClose);
+            if (err) {
+                chunks.length = 0;
+                reject(err);
+            }
+            else
+                resolve(Buffer.concat(chunks));
+        };
+        const onData = (c) => {
+            total += c.length;
+            if (total > limit)
+                return finish(new BodyTooLarge());
+            chunks.push(c);
+        };
+        const onEnd = () => finish();
+        const onError = () => finish(new BodyAborted());
+        const onClose = () => { if (!req.complete)
+            finish(new BodyAborted()); };
+        req.on('data', onData);
+        req.on('end', onEnd);
+        req.on('error', onError);
+        req.on('close', onClose);
+    });
+}
+/**
+ * 413 and stop. Nothing more is buffered. So the client can still read the 413, up to
+ * DISCARD_BUDGET_BYTES more are thrown away for at most DISCARD_GRACE_MS; past either
+ * limit the socket is dropped (the client may then see a reset instead of the 413).
+ */
+function tooLarge(req, res) {
+    plain(res, 413, `The request body is larger than the SAP link accepts (${MAX_REQUEST_BODY_BYTES / (1024 * 1024)} MiB).`);
+    const socket = req.socket;
+    let discarded = 0;
+    const drop = () => { clearTimeout(timer); req.off('data', onData); socket.destroy(); };
+    const onData = (c) => { discarded += c.length; if (discarded > DISCARD_BUDGET_BYTES)
+        drop(); };
+    const timer = setTimeout(drop, DISCARD_GRACE_MS);
+    timer.unref();
+    socket.once('close', () => clearTimeout(timer));
+    req.on('data', onData);
+    req.resume();
+}
+export async function startSapLink(opts) {
+    let listenPort = opts.listenPort;
+    const roleTimeoutMs = opts.roleTimeoutMs ?? DEFAULT_ROLE_TIMEOUT_MS;
+    const handle = async (req, res) => {
+        // 1. R1 — browser / DNS-rebinding defence, before anything else.
+        const refused = browserGuard(req, listenPort);
+        if (refused)
+            return plain(res, refused.status, refused.message, true);
+        const declared = req.headers['content-length'];
+        if (declared !== undefined && !(Number(declared) <= MAX_REQUEST_BODY_BYTES))
+            return tooLarge(req, res);
+        // 2. Role, fresh on every request. Fail closed if it cannot be read.
+        let role;
+        try {
+            role = await readRole(opts.getRole, roleTimeoutMs);
+        }
+        catch {
+            return plain(res, 503, SETTINGS_UNREADABLE);
+        }
+        // 3. Policy. Only its output is forwarded from here on.
+        const d = decideRequest({
+            method: req.method ?? 'GET', rawUrl: req.url ?? '/',
+            headers: req.headers,
+            allowedPrefixes: opts.allowedPrefixes, alias: opts.alias, role,
+        });
+        if (!d.allow)
+            return plain(res, d.status, d.message);
+        // 4. Body (capped). GET and HEAD never carry one upstream.
+        let body;
+        try {
+            body = await readBody(req, MAX_REQUEST_BODY_BYTES);
+        }
+        catch (e) {
+            if (e instanceof BodyTooLarge)
+                return tooLarge(req, res);
+            res.destroy();
+            return;
+        }
+        // A write: read the role again now the body is in. A flip during the upload wins.
+        if (d.write) {
+            let again;
+            try {
+                again = await readRole(opts.getRole, roleTimeoutMs);
+            }
+            catch {
+                return plain(res, 503, SETTINGS_UNREADABLE);
+            }
+            if (again !== 'dev')
+                return plain(res, 403, writesBlockedMessage(opts.alias, again));
+        }
+        const noBody = d.method === 'GET' || d.method === 'HEAD';
+        if (noBody)
+            body = Buffer.alloc(0);
+        const logWrite = (status) => {
+            try {
+                appendWriteRow(opts.writeLogFile, { at: new Date().toISOString(), method: d.method, path: d.upstreamPath.split('?')[0], status }, opts.secret);
+            }
+            catch {
+                /* intentionally silent: no logging of anything request-related */
+            }
+        };
+        const flat = {};
+        for (const [k, v] of Object.entries(req.headers))
+            if (v !== undefined)
+                flat[k] = Array.isArray(v) ? v.join(', ') : v;
+        // 5. Upstream. Any throw maps to a fixed plain message. The first 401 and the
+        // upstream's latched refusal (ELOGINREJECTED, nothing sent) share one message.
+        const loginRejected = () => `${opts.alias} rejected the stored login for ${opts.secret.username}. Update the stored SAP password for this alias, then start the SAP link again (sap_link start).`;
+        let up;
+        try {
+            up = await opts.upstream.send({ method: d.method, path: d.upstreamPath, servicePrefix: d.servicePrefix, headers: flat, body, write: d.write });
+        }
+        catch (e) {
+            // R16: the write may have reached SAP. Log it as status 0 = outcome unknown.
+            if (d.write)
+                logWrite(0);
+            const code = e && typeof e === 'object' && typeof e.code === 'string' ? e.code : '';
+            if (REACH_CODES.has(code))
+                return plain(res, 502, reachMessage(opts.alias, opts.host, opts.port));
+            if (code === 'ELOGINREJECTED')
+                return plain(res, 502, loginRejected());
+            if (code === 'ERESPONSETOOLARGE')
+                return plain(res, 502, `The response from ${opts.alias} was too large.`);
+            return plain(res, 502, `The SAP link could not complete the request to ${opts.alias}.`);
+        }
+        // 6. Write log. The write already happened: a failed append must not hide the answer.
+        if (d.write)
+            logWrite(up.status);
+        // 7. Answer.
+        if (!Number.isInteger(up.status) || up.status < 200 || up.status > 599) {
+            return plain(res, 502, `The SAP link could not complete the request to ${opts.alias}.`);
+        }
+        if (up.status === 401)
+            return plain(res, 502, loginRejected());
+        const headers = {};
+        for (const [k, v] of Object.entries(up.headers ?? {})) {
+            const lower = k.toLowerCase();
+            if (!FRAMING_OUT.has(lower) && !OWN_OUT.has(lower))
+                headers[k] = v;
+        }
+        headers['x-content-type-options'] = 'nosniff';
+        headers['content-security-policy'] = "sandbox; default-src 'none'";
+        const isHead = d.method === 'HEAD' || req.method === 'HEAD';
+        const bodyless = isHead || up.status === 204 || up.status === 304;
+        if (!bodyless)
+            headers['content-length'] = up.body.length;
+        try {
+            res.writeHead(up.status, headers);
+        }
+        catch {
+            // Invalid status or header value from upstream: answer plainly instead.
+            return plain(res, 502, `The SAP link could not complete the request to ${opts.alias}.`);
+        }
+        if (bodyless)
+            res.end();
+        else
+            res.end(up.body);
+    };
+    const server = http.createServer({ requireHostHeader: false }, (req, res) => {
+        handle(req, res).catch(() => {
+            try {
+                plain(res, 502, `The SAP link could not complete the request to ${opts.alias}.`);
+            }
+            catch {
+                res.destroy();
+            }
+        });
+    });
+    server.headersTimeout = HEADERS_TIMEOUT_MS;
+    server.requestTimeout = REQUEST_TIMEOUT_MS;
+    await new Promise((resolve, reject) => {
+        const onError = (e) => {
+            reject(e.code === 'EADDRINUSE'
+                ? new SapLinkStartError('port-taken', `Port ${opts.listenPort} is in use. Stop the program using it, or change the port in package.json ([s4] credentials.url) and start the SAP link again.`)
+                : new SapLinkStartError('other', `The SAP link could not start: ${e.message}`));
+        };
+        server.once('error', onError);
+        try {
+            server.listen(opts.listenPort, '127.0.0.1', () => { server.off('error', onError); resolve(); });
+        }
+        catch (e) {
+            server.off('error', onError);
+            onError(e);
+        }
+    });
+    // After start, a server error must never crash CSPeach. Nothing is logged.
+    server.on('error', () => { });
+    listenPort = server.address().port;
+    let closing;
+    return {
+        url: `http://127.0.0.1:${listenPort}`,
+        listenPort,
+        alias: opts.alias,
+        writeLogFile: opts.writeLogFile,
+        close: () => {
+            closing ??= new Promise((r) => {
+                server.close(() => r());
+                server.closeAllConnections();
+            });
+            return closing;
+        },
+    };
+}