@cspeach/cli 1.1.22 → 1.1.23

package/dist/sap-link/policy.js

@@ -0,0 +1,185 @@
+const READS = new Set(['GET', 'HEAD']);
+const WRITES = new Set(['POST', 'PUT', 'PATCH', 'MERGE', 'DELETE']);
+const OVERRIDE_HEADERS = ['x-http-method', 'x-http-method-override'];
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR = /[\u0000-\u001f\u007f]/;
+/** All values for a header, matched case-insensitively; arrays are flattened. */
+function headerValues(h, name) {
+    const out = [];
+    for (const [k, v] of Object.entries(h)) {
+        if (k.toLowerCase() !== name)
+            continue;
+        if (Array.isArray(v))
+            out.push(...v);
+        else if (v !== undefined)
+            out.push(v);
+    }
+    return out;
+}
+/**
+ * The method the request really performs, or an error when the override headers are
+ * unusable (unknown/empty verb, or conflicting values).
+ */
+/** Echo a verb only when it is plain letters; never reflect arbitrary text. */
+function unknownVerbMessage(verb) {
+    if (verb === '')
+        return 'The SAP link does not forward empty requests.';
+    if (/^[A-Z]{1,16}$/.test(verb))
+        return `The SAP link does not forward ${verb} requests.`;
+    return 'The SAP link does not forward that method.';
+}
+function effectiveMethod(realMethod, h) {
+    const real = realMethod.trim().toUpperCase();
+    if (!READS.has(real) && !WRITES.has(real)) {
+        return { error: unknownVerbMessage(real) };
+    }
+    const overrides = OVERRIDE_HEADERS.flatMap((n) => headerValues(h, n)).map((v) => v.trim().toUpperCase());
+    if (overrides.length === 0)
+        return { method: real, real };
+    const distinct = new Set(overrides);
+    if (distinct.size > 1) {
+        return { error: 'The SAP link refuses requests with conflicting method override headers.' };
+    }
+    const override = overrides[0];
+    if (!READS.has(override) && !WRITES.has(override)) {
+        return { error: unknownVerbMessage(override) };
+    }
+    return { method: override, real, override };
+}
+/** Each `%` must be `%XY` decoding to a printable ASCII char other than . / \ % ;. */
+function pathEncodingIsSafe(rawPath) {
+    for (let i = 0; i < rawPath.length; i++) {
+        if (rawPath[i] !== '%')
+            continue;
+        const hex = rawPath.slice(i + 1, i + 3);
+        if (!/^[0-9a-fA-F]{2}$/.test(hex))
+            return false;
+        const code = parseInt(hex, 16);
+        if (code < 0x20 || code >= 0x7f)
+            return false;
+        if (code === 0x2e || code === 0x2f || code === 0x5c || code === 0x25 || code === 0x3b)
+            return false;
+        i += 2;
+    }
+    return true;
+}
+/** Lower-cased, slash-led, no trailing slash; null when the prefix is not a clean path. */
+function normPrefix(p) {
+    const withSlash = p.startsWith('/') ? p : `/${p}`;
+    const trimmed = withSlash.replace(/\/+$/, '');
+    if (trimmed === '' || trimmed === '/')
+        return null;
+    if (/[%\\?#;]/.test(trimmed) || /[^\x20-\x7e]/.test(trimmed))
+        return null;
+    const segments = trimmed.slice(1).split('/');
+    if (segments.some((s) => s === '' || s === '.' || s === '..'))
+        return null;
+    return trimmed.toLowerCase();
+}
+function isBatchPath(pathname) {
+    return pathname.split('/').some((seg) => {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(seg);
+        }
+        catch {
+            decoded = seg;
+        }
+        return decoded.split(';', 1)[0].trim().toLowerCase() === '$batch';
+    });
+}
+/**
+ * True when any query parameter name (decoded, trimmed) starts with `sap-`, except
+ * sap-language. 'malformed' when a name cannot be decoded (caller fails closed).
+ */
+function hasSapQueryParam(rawQuery) {
+    for (const part of rawQuery.split(/[&;]/)) {
+        const rawName = part.split('=', 1)[0];
+        let name;
+        try {
+            name = decodeURIComponent(rawName.replace(/\+/g, ' '));
+        }
+        catch {
+            return 'malformed';
+        }
+        const n = name.trim().toLowerCase();
+        if (n.startsWith('sap-') && n !== 'sap-language')
+            return true;
+    }
+    return false;
+}
+export function writesBlockedMessage(alias, role) {
+    const now = role === undefined ? 'has no role set' : `has role ${role}`;
+    return `Writes to ${alias} need role dev. ${alias} ${now}. Set it with: cspeach config set sap.${alias}.role dev`;
+}
+export function decideRequest(input) {
+    const m = effectiveMethod(input.method, input.headers);
+    if ('error' in m)
+        return { allow: false, status: 400, message: m.error };
+    const method = m.method;
+    const verbIsWrite = WRITES.has(m.real) || (m.override !== undefined && WRITES.has(m.override));
+    const raw = input.rawUrl;
+    if (!raw.startsWith('/') || raw.startsWith('//')) {
+        return { allow: false, status: 400, message: 'The SAP link only accepts paths on this machine, not full URLs.' };
+    }
+    if (CONTROL_CHAR.test(raw)) {
+        return { allow: false, status: 400, message: 'The SAP link refuses paths with control characters.' };
+    }
+    const rawPath = raw.split(/[?#]/, 1)[0];
+    if (rawPath.includes('\\') || /[^\x00-\x7f]/.test(rawPath) || !pathEncodingIsSafe(rawPath)) {
+        return { allow: false, status: 400, message: 'The SAP link refuses encoded or backslash paths.' };
+    }
+    const url = new URL(raw, 'http://127.0.0.1');
+    if (url.host !== '127.0.0.1') {
+        return { allow: false, status: 400, message: 'The SAP link only accepts paths on this machine, not full URLs.' };
+    }
+    for (const seg of url.pathname.split('/')) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(seg);
+        }
+        catch {
+            return { allow: false, status: 400, message: 'The SAP link refuses encoded or backslash paths.' };
+        }
+        const bare = decoded.split(';', 1)[0].trim();
+        if (bare === '.' || bare === '..') {
+            return { allow: false, status: 400, message: 'The SAP link refuses dot segments with parameters.' };
+        }
+    }
+    const pathLower = url.pathname.toLowerCase();
+    const usable = input.allowedPrefixes
+        .map((original) => ({ original, norm: normPrefix(original) }))
+        .filter((p) => p.norm !== null);
+    const hit = usable.find((p) => pathLower === p.norm || pathLower.startsWith(`${p.norm}/`) || pathLower.startsWith(`${p.norm};`));
+    if (!hit) {
+        return {
+            allow: false,
+            status: 404,
+            message: `The SAP link only forwards the services this project imported: ` +
+                `${usable.map((p) => p.original).join(', ') || '(none)'}.`,
+        };
+    }
+    // Only `;v=<digits>` directly on the service segment; no other `;` anywhere.
+    const afterPrefix = pathLower.slice(hit.norm.length);
+    const version = /^;v=\d+(?=\/|$)/.exec(afterPrefix);
+    const rest = version ? afterPrefix.slice(version[0].length) : afterPrefix;
+    if (rest.includes(';')) {
+        return {
+            allow: false,
+            status: 400,
+            message: 'The SAP link only accepts ;v=<number> after the service name. Other path parameters are refused.',
+        };
+    }
+    if (hasSapQueryParam(url.search.replace(/^\?/, '')) !== false) {
+        return {
+            allow: false,
+            status: 400,
+            message: 'The SAP link refuses sap- query parameters. It uses the client and login from your SAP settings.',
+        };
+    }
+    const write = verbIsWrite || isBatchPath(url.pathname);
+    if (write && input.role !== 'dev') {
+        return { allow: false, status: 403, message: writesBlockedMessage(input.alias, input.role) };
+    }
+    return { allow: true, write, method, upstreamPath: url.pathname + url.search, servicePrefix: hit.original };
+}

package/dist/sap-link/project.js

@@ -0,0 +1,163 @@
+// cspeach-cli/src/sap-link/project.ts
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+export class LinkConfigError extends Error {
+}
+const LOOPBACK = new Set(['127.0.0.1', 'localhost']);
+/** Keys that carry a secret. Matched case-insensitively at any depth of an S/4 entry. None may sit in package.json. */
+const SECRET_KEYS = new Set([
+    'user', 'username', 'password', 'token', 'clientsecret', 'client_secret',
+    'authentication', 'headers', 'key', 'apikey',
+]);
+/** The only OData roots the SAP link may be pointed at, and how many segments name exactly one service. */
+const ODATA_ROOTS = [
+    { root: '/sap/opu/odata/', segments: 2, version: 'v2' }, // <namespace>/<SERVICE>[;v=N]
+    { root: '/sap/opu/odata4/', segments: 6, version: 'v4' }, // <ns>/<group>/<repo>/<ns>/<service>/<version>
+];
+const MAX_PACKAGE_BYTES = 5 * 1024 * 1024;
+const MAX_DEPTH = 20;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/**
+ * Raw path chars allowed: printable ASCII 0x21-0x7e that the URL parser leaves as-is,
+ * i.e. without `"` `<` `>` backtick `{` `|` `}` `^` `%` and backslash.
+ */
+const PATH_CHARS = /^[!#$&-;=?-[\]_a-z~]*$/;
+/** A URL with a login in it (`scheme://user[:pass]@host`). */
+const URL_USERINFO = /:\/\/[^/?#\s]*@/;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const loginMessage = (name) => `package.json holds a login for ${name}. Remove it — the SAP link adds the login from your keychain.`;
+/** Walks a whole `requires` entry and refuses any secret-bearing key at any depth. Never reports values. */
+function scanForSecrets(name, value, depth = 0, seen = new Set()) {
+    if (typeof value === 'string' && URL_USERINFO.test(value))
+        throw new LinkConfigError(loginMessage(name));
+    if (typeof value !== 'object' || value === null)
+        return;
+    if (depth > MAX_DEPTH)
+        throw new LinkConfigError(`The entry for ${name} in package.json is nested too deeply.`);
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            scanForSecrets(name, item, depth + 1, seen);
+        return;
+    }
+    for (const [k, v] of Object.entries(value)) {
+        if (SECRET_KEYS.has(k.toLowerCase()))
+            throw new LinkConfigError(loginMessage(name));
+        scanForSecrets(name, v, depth + 1, seen);
+    }
+}
+/** Checks one service's `[s4]` URL and returns its port and allowlist prefix. Never echoes the URL. */
+function checkUrl(name, raw) {
+    // Before parsing: `URL` silently strips tabs, newlines and leading/trailing controls.
+    if (CONTROL_CHARS.test(raw))
+        throw new LinkConfigError(`${name}: the [s4] URL holds control characters.`);
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new LinkConfigError(`${name}: the [s4] URL is not a valid URL.`);
+    }
+    if (u.username !== '' || u.password !== '')
+        throw new LinkConfigError(loginMessage(name));
+    const authority = /^[a-z][a-z0-9+.-]*:[/\\]{2}([^/\\?#]*)/i.exec(raw);
+    const rawAuthority = authority?.[1] ?? '';
+    // `URL` drops the default port, so an explicit :80 would otherwise read as "no port".
+    if (u.protocol === 'http:' && u.port === '' && /:0*80$/.test(rawAuthority)) {
+        throw new LinkConfigError(`${name}: port 80 is not supported for the SAP link. Use another port, such as 4005.`);
+    }
+    if (u.protocol !== 'http:' || !LOOPBACK.has(u.hostname) || u.port === '' || !authority) {
+        throw new LinkConfigError(`${name}: the [s4] URL must point at the SAP link on 127.0.0.1 with a port.`);
+    }
+    const port = Number(u.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new LinkConfigError(`${name}: the [s4] URL port must be a whole number from 0 to 65535.`);
+    }
+    // Check the raw string too: `URL` drops an empty `?` or `#`.
+    if (u.search !== '' || u.hash !== '' || raw.includes('?') || raw.includes('#')) {
+        throw new LinkConfigError(`${name}: the [s4] URL must not have a query or fragment.`);
+    }
+    const prefix = u.pathname.replace(/\/+$/, '');
+    const root = ODATA_ROOTS.find((r) => prefix.toLowerCase().startsWith(r.root));
+    if (!root || prefix.length <= root.root.length) {
+        throw new LinkConfigError(`${name}: the [s4] URL path must start with /sap/opu/odata/ or /sap/opu/odata4/ and name a service.`);
+    }
+    // Judge the RAW path, not what normalisation made of it.
+    const rawPath = raw.slice(authority[0].length).replace(/\/+$/, '');
+    const rawSegments = rawPath.split('/').slice(1);
+    if (rawPath.includes('%') || rawPath.includes('\\') ||
+        rawSegments.some((s) => {
+            // `..;v=1` climbs on servers that strip matrix params, so judge the part before `;`.
+            const bare = s.split(';')[0];
+            return bare === '' || bare === '.' || bare === '..';
+        })) {
+        throw new LinkConfigError(`${name}: the [s4] URL path must not hold dot segments, encoded characters, backslashes or empty segments.`);
+    }
+    // Anything the parser percent-encodes (space, quotes, braces, non-ASCII, ...) would come back
+    // as `%XY` in the prefix, which the policy drops. Refuse it on both sides of parsing.
+    if (!PATH_CHARS.test(rawPath) || u.pathname.includes('%')) {
+        throw new LinkConfigError(`${name}: the [s4] URL path may only hold plain ASCII letters, digits and URL punctuation.`);
+    }
+    const segments = prefix.slice(root.root.length).split('/');
+    if (segments.length !== root.segments || segments.some((s) => s === '')) {
+        throw new LinkConfigError(`${name}: the [s4] URL path must name exactly one service, like /sap/opu/odata/sap/API_BUSINESS_PARTNER.`);
+    }
+    const last = segments.length - 1;
+    const matrixOk = segments.every((s, i) => !s.includes(';') || (root.version === 'v2' && i === last && /^[^;]+;v=\d+$/.test(s)));
+    if (!matrixOk) {
+        throw new LinkConfigError(`${name}: the [s4] URL path may only carry ;v=<number> on the service name.`);
+    }
+    // The policy matches the bare service and accepts `;v=N` right after it, so the prefix drops it.
+    return { port, prefix: prefix.replace(/;v=\d+$/, '') };
+}
+async function readPackageJson(projectDir) {
+    const file = path.join(projectDir, 'package.json');
+    let size;
+    try {
+        size = (await fs.stat(file)).size;
+    }
+    catch {
+        throw new LinkConfigError(`No readable package.json in ${projectDir}.`);
+    }
+    if (size > MAX_PACKAGE_BYTES) {
+        throw new LinkConfigError(`package.json in ${projectDir} is larger than 5 MB. The SAP link will not read it.`);
+    }
+    try {
+        return JSON.parse(await fs.readFile(file, 'utf8'));
+    }
+    catch {
+        throw new LinkConfigError(`No readable package.json in ${projectDir}.`);
+    }
+}
+/** The generated app's `[s4]` profile points each remote service at the SAP link (spec §6.2). */
+export async function readLinkTargets(projectDir) {
+    const pkg = await readPackageJson(projectDir);
+    const cds = isObject(pkg) ? pkg.cds : undefined;
+    const requires = isObject(cds) && isObject(cds.requires) ? cds.requires : {};
+    const services = [];
+    const ports = new Set();
+    for (const [name, entry] of Object.entries(requires)) {
+        if (!isObject(entry))
+            continue;
+        const profile = entry['[s4]'];
+        if (!isObject(profile))
+            continue;
+        const creds = profile.credentials;
+        if (!isObject(creds) || typeof creds.url !== 'string')
+            continue;
+        // Only S/4 entries are scanned: other entries (e.g. mocked auth users) legitimately hold test passwords.
+        scanForSecrets(name, entry);
+        const { port, prefix } = checkUrl(name, creds.url);
+        ports.add(port);
+        services.push({ name, prefix });
+    }
+    if (services.length === 0) {
+        throw new LinkConfigError('No S/4 services in this project. Import one first (cap_metadata_import, then cds import).');
+    }
+    if (ports.size !== 1)
+        throw new LinkConfigError('All [s4] URLs must use one port — the SAP link listens on one.');
+    return { port: [...ports][0], services };
+}

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;
+}