@cspeach/cli 1.1.22 → 1.1.24

package/dist/tools/cap/metadata-import.js

@@ -0,0 +1,325 @@
+// cspeach-cli/src/tools/cap/metadata-import.ts
+//
+// CAP phase 2, Task 10 — `cap_metadata_import`: GET an S/4 OData service's
+// `$metadata` with the stored SAP login and write it to
+// `<projectDir>/srv/external/<apiName>.edmx`. The model then runs `cds import`.
+//
+// Security posture (owner hardening on top of the brief):
+// - Inputs: apiName is a plain name; servicePath is a Gateway OData path only
+//   (V2 `/sap/opu/odata/<ns>/<SERVICE>[;v=N]`, V4 `/sap/opu/odata4/` + 6 segments),
+//   printable ASCII, no `..`, `%`, `\`, `?`, `#`. Bad input fetches nothing.
+// - The file stays in the workspace: resolveSafePath + the filesystem denylist +
+//   a realpath check on the nearest existing folder (catches a linked
+//   `srv/external`), and an existing symlink at the target is refused (lstat).
+//   The write goes to a fresh temp file then renames over the target, so a link
+//   planted after the check is replaced, never followed.
+// - The answer must be HTTP 200, not HTML, at most 20 MB, start with
+//   `<edmx:Edmx` within its first 2 KB (after BOM / XML declaration /
+//   whitespace) and end with `</edmx:Edmx>`. Anything else is a plain error and
+//   NOTHING is written — not even the folder. The body is never echoed.
+// - Connection errors are mapped to plain text; raw exception messages (which
+//   can carry headers, cookies or user names) never reach the tool result.
+// - apiName refuses Windows device names (CON, NUL, COM1...); projectDir allows
+//   only letters, digits, `.`, `_`, `-`, space and `/` or `\` — no `:`, so an
+//   NTFS stream suffix (`.git::$INDEX_ALLOCATION`) cannot slip past the denylist.
+// - The answer is read with linear tag scans (indexOf with cached `>` and `<`
+//   positions), never a backtracking regex over the whole body: a hostile
+//   $metadata of repeated openers cannot block the event loop.
+// - isMutating: true (ruling R18) — it writes a workspace file, so read-only
+//   plan-phase subagents never get it. Precedent: fiori_deploy_config.
+//
+// Accepted residual risks:
+// - Folder-swap race: between the realpath re-check after mkdir and the rename,
+//   a process on this machine could swap `srv/external` for a link. That needs
+//   a local attacker who can already write the workspace; the rename still
+//   never follows a link at the file itself.
+// - The 20 MB cap applies after download: SapConnection.get returns the whole
+//   body as a string with no streaming limit, so a huge answer is buffered
+//   before it is refused. A pre-download cap needs a limit in sap-client.
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { registerTool } from '../index.js';
+import { resolveSafePath, isDenylistedPath, BLOCKED_PREFIXES } from '../_filesystem-shared.js';
+import { loadConfig } from '../../config/loader.js';
+import { PlainFetchError, plainSapFetchError } from './_fetch-errors.js';
+const NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,59}$/;
+/** Windows device names: `CON.edmx` opens the console, not a file. */
+const RESERVED_NAME_RE = /^(CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])$/i;
+/** projectDir characters. No `:` (drive letters, NTFS streams), no wildcards, no control chars. */
+const PROJECT_DIR_RE = /^[A-Za-z0-9._\-/\\ ]*$/;
+/** Longest start tag we read attributes from; longer ones are skipped. */
+const MAX_TAG_CHARS = 4096;
+const SEG = '[A-Za-z0-9_]+';
+const V2_PATH_RE = new RegExp(`^/sap/opu/odata/${SEG}/${SEG}(?:;v=\\d+)?/?$`);
+const V4_PATH_RE = new RegExp(`^/sap/opu/odata4(?:/${SEG}){6}/?$`);
+const PRINTABLE_ASCII_RE = /^[\x20-\x7E]+$/;
+const HEAD_BYTES = 2048;
+/** Largest $metadata we accept (S/4 API_BUSINESS_PARTNER is ~0.5 MB). */
+export const MAX_METADATA_BYTES = 20 * 1024 * 1024;
+/** Entity-set names we print: plain identifiers only (the answer is SAP-supplied text). */
+const SET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const MAX_SETS_SHOWN = 40;
+const PATH_SHAPE = 'servicePath must be a Gateway OData path: /sap/opu/odata/<namespace>/<SERVICE> (optionally ending ;v=<number>) ' +
+    'or /sap/opu/odata4/ followed by 6 segments. No host, query, "..", "%", "\\", "?" or "#".';
+/**
+ * Map a connection error to one plain line. Never includes the raw message:
+ * sap-client and fetch errors can carry headers, cookies or the user name.
+ * (Shared with sap_service_catalog via ./_fetch-errors.ts.)
+ */
+export function plainFetchError(err, alias, host, port) {
+    return plainSapFetchError(err, alias, host, port, `Could not read the metadata from ${alias}. Check the SAP login for this system and try again.`);
+}
+function validServicePath(p) {
+    if (typeof p !== 'string' || !PRINTABLE_ASCII_RE.test(p))
+        return undefined;
+    if (p.includes('..') || /[%\\?#]/.test(p))
+        return undefined;
+    if (!V2_PATH_RE.test(p) && !V4_PATH_RE.test(p))
+        return undefined;
+    return p.replace(/\/+$/, '');
+}
+/** Looks like EDMX: root `<edmx:Edmx` in the first 2 KB and a closing tag at the end. */
+function looksLikeEdmx(body) {
+    const head = body.slice(0, HEAD_BYTES);
+    if (!/^\uFEFF?\s*(?:<\?xml\b[^>]*\?>\s*)?<edmx:Edmx[\s>]/.test(head))
+        return false;
+    return body.trimEnd().endsWith('</edmx:Edmx>');
+}
+const isTagNameEnd = (c) => c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d || c === 0x3e || c === 0x2f;
+/**
+ * Call `fn` with the attribute text of every well-formed `<name ...>` start tag.
+ * Linear in the body: the next `>` and next `<` positions are cached and only
+ * move forward, so repeated unclosed openers cost O(1) each. A tag longer than
+ * MAX_TAG_CHARS, or one holding another `<` before its `>`, is skipped.
+ * `fn` returns true to stop early.
+ */
+function forEachStartTag(body, name, fn) {
+    const open = `<${name}`;
+    let pos = 0;
+    let gt = -1;
+    let lt = -1;
+    let ltDone = false;
+    for (;;) {
+        pos = body.indexOf(open, pos);
+        if (pos < 0)
+            return;
+        const attrStart = pos + open.length;
+        if (!isTagNameEnd(body.charCodeAt(attrStart))) {
+            pos = attrStart;
+            continue;
+        }
+        if (gt < attrStart) {
+            gt = body.indexOf('>', attrStart);
+            if (gt < 0)
+                return;
+        }
+        if (!ltDone && lt < attrStart) {
+            lt = body.indexOf('<', attrStart);
+            if (lt < 0)
+                ltDone = true;
+        }
+        const wellFormed = gt - attrStart <= MAX_TAG_CHARS && (ltDone || lt > gt);
+        if (wellFormed) {
+            if (fn(body.slice(attrStart, gt)) === true)
+                return;
+            pos = gt + 1;
+        }
+        else {
+            pos = attrStart;
+        }
+    }
+}
+/** v4 when the root edmx:Edmx says Version="4.0"; v2 when edmx:DataServices carries m:DataServiceVersion. */
+export function odataVersion(body) {
+    const root = /<edmx:Edmx\b([^>]*)>/.exec(body.slice(0, HEAD_BYTES));
+    const rootVersion = root ? /(?:^|\s)Version="([^"]*)"/.exec(root[1] ?? '') : null;
+    if (rootVersion?.[1] === '4.0' || rootVersion?.[1] === '4.01')
+        return 'v4';
+    let v2 = false;
+    forEachStartTag(body, 'edmx:DataServices', (attrs) => {
+        v2 = /(?:^|\s)m:DataServiceVersion="[\d.]+"/.test(attrs);
+        return v2;
+    });
+    return v2 ? 'v2' : undefined;
+}
+export function entitySets(body) {
+    const out = [];
+    forEachStartTag(body, 'EntitySet', (attrs) => {
+        const n = /(?:^|\s)Name="([^"]*)"/.exec(attrs)?.[1] ?? '';
+        if (SET_NAME_RE.test(n))
+            out.push(n);
+    });
+    return out;
+}
+const isInside = (root, p) => {
+    const rel = path.relative(root, p);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+/** Realpath of the nearest existing ancestor of `p` must sit inside the real workspace root. */
+async function nearestExistingInside(rootReal, p) {
+    let cur = p;
+    for (;;) {
+        try {
+            return isInside(rootReal, await fs.realpath(cur));
+        }
+        catch {
+            const up = path.dirname(cur);
+            if (up === cur)
+                return false;
+            cur = up;
+        }
+    }
+}
+async function isSymlink(p) {
+    try {
+        return (await fs.lstat(p)).isSymbolicLink();
+    }
+    catch {
+        return false; // does not exist
+    }
+}
+export async function capMetadataImportHandler(args, ctx, deps = {}) {
+    const fail = (m) => ({ content: `error: ${m}`, is_error: true });
+    const apiName = typeof args.apiName === 'string' ? args.apiName : '';
+    if (!NAME_RE.test(apiName)) {
+        return fail('apiName must be a plain name like API_BUSINESS_PARTNER: a letter first, then letters, digits or _, at most 60.');
+    }
+    if (RESERVED_NAME_RE.test(apiName)) {
+        return fail(`apiName ${apiName} is a reserved Windows device name. Use another name, such as API_${apiName.toUpperCase()}.`);
+    }
+    const svc = validServicePath(args.servicePath);
+    if (!svc)
+        return fail(PATH_SHAPE);
+    const rawDir = args.projectDir === undefined ? '.' : args.projectDir;
+    if (typeof rawDir !== 'string' || !PROJECT_DIR_RE.test(rawDir)) {
+        return fail('projectDir must be a relative folder inside the workspace, using only letters, digits, ".", "_", "-", space and "/".');
+    }
+    // One separator on every OS, so `apps\bp` means the same folder on Windows and Linux.
+    const projectDir = rawDir.replace(/\\/g, '/') || '.';
+    // ── Where the file goes: inside the workspace, not denylisted, not a link. ──
+    const outsideMsg = 'projectDir must be a folder inside the workspace (not .git or .cspeach).';
+    let target;
+    try {
+        target = resolveSafePath(ctx.cwd, path.join(projectDir, 'srv', 'external', `${apiName}.edmx`));
+    }
+    catch {
+        return fail(outsideMsg);
+    }
+    const rootAbs = path.resolve(ctx.cwd);
+    const { blocked, relFromRoot } = isDenylistedPath(target, rootAbs);
+    const firstSeg = (relFromRoot.split('/')[0] ?? '').toLowerCase();
+    if (blocked || BLOCKED_PREFIXES.some((b) => b.toLowerCase() === firstSeg))
+        return fail(outsideMsg);
+    let rootReal;
+    try {
+        rootReal = await fs.realpath(rootAbs);
+    }
+    catch {
+        return fail('The workspace folder could not be read.');
+    }
+    if (!(await nearestExistingInside(rootReal, path.dirname(target)))) {
+        return fail('The target folder links outside the workspace. Nothing was written.');
+    }
+    if (await isSymlink(target)) {
+        return fail(`${relFromRoot} is a symlink. Remove it first; the import never writes through a link.`);
+    }
+    // ── Fetch. ──
+    const get = deps.get ?? (async (p) => {
+        const cfg = await loadConfig();
+        const sys = cfg.sap[ctx.sapAlias];
+        if (!sys)
+            throw new PlainFetchError(`No SAP system "${ctx.sapAlias}" is configured.`);
+        try {
+            const { getConnection } = await import('../../sap/connection-manager.js');
+            const conn = await getConnection(ctx.sapAlias, sys);
+            const r = await conn.get(p, 'application/xml');
+            const contentType = r.headers?.get?.('content-type');
+            return { status: r.status, body: r.body, ...(contentType ? { contentType } : {}) };
+        }
+        catch (err) {
+            throw new PlainFetchError(plainFetchError(err, ctx.sapAlias, sys.host, sys.port));
+        }
+    });
+    const metaPath = `${svc}/$metadata`;
+    let r;
+    try {
+        r = await get(metaPath);
+    }
+    catch (err) {
+        return fail(err instanceof PlainFetchError
+            ? err.message
+            : `Could not read the metadata from ${ctx.sapAlias}. Check the SAP login for this system and try again.`);
+    }
+    // ── Validate the answer. Nothing is written unless all checks pass. ──
+    if (r.status !== 200) {
+        return fail(`${metaPath} answered HTTP ${r.status}. Check the service is active (sap_service_catalog) and your user may read it. Nothing was written.`);
+    }
+    const body = typeof r.body === 'string' ? r.body : '';
+    const bytes = Buffer.byteLength(body, 'utf8');
+    if (bytes > MAX_METADATA_BYTES) {
+        return fail(`${metaPath} answered with more than 20 MB. That is too large for an import. Nothing was written.`);
+    }
+    if ((r.contentType && /html/i.test(r.contentType)) || !looksLikeEdmx(body)) {
+        return fail(`${metaPath} answered, but it is not OData metadata (looks like an HTML, login or error page). Nothing was written.`);
+    }
+    // ── Write: temp file (exclusive create) then rename over the target. ──
+    try {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        if (!(await nearestExistingInside(rootReal, path.dirname(target)))) {
+            return fail('The target folder links outside the workspace. Nothing was written.');
+        }
+        if (await isSymlink(target)) {
+            return fail(`${relFromRoot} is a symlink. Remove it first; the import never writes through a link.`);
+        }
+        const tmp = `${target}.${randomBytes(6).toString('hex')}.tmp`;
+        try {
+            await fs.writeFile(tmp, body, { encoding: 'utf8', flag: 'wx' });
+            await fs.rename(tmp, target);
+        }
+        catch (err) {
+            await fs.rm(tmp, { force: true }).catch(() => undefined);
+            throw err;
+        }
+    }
+    catch {
+        return fail(`Could not write ${relFromRoot}. Check the folder is writable.`);
+    }
+    const sets = entitySets(body);
+    const odata = odataVersion(body);
+    const rel = path.relative(path.resolve(rootAbs, projectDir), target).split(path.sep).join('/');
+    const relProject = path.relative(rootAbs, path.resolve(rootAbs, projectDir)).split(path.sep).join('/');
+    const where = relProject === '' ? 'in the project root' : `in ${/\s/.test(relProject) ? JSON.stringify(relProject) : relProject}`;
+    return {
+        content: [
+            `Wrote ${rel} (${bytes} bytes, ${odata ? `OData ${odata}` : 'OData version unknown'}).`,
+            `Entity sets: ${sets.length ? sets.slice(0, MAX_SETS_SHOWN).join(', ') : '(none found)'}` +
+                `${sets.length > MAX_SETS_SHOWN ? ` … (${sets.length} total)` : ''}`,
+            `Next: cds import ${rel} --as cds   (${where}), then add the [s4] profile URL: http://127.0.0.1:4005${svc}`,
+        ].join('\n'),
+    };
+}
+registerTool({
+    name: 'cap_metadata_import',
+    description: 'Fetch an S/4 OData service\'s $metadata with the stored SAP login and write it to <projectDir>/srv/external/<apiName>.edmx ' +
+        '(CAP phase 2). It only writes that one file; run `cds import` on it afterwards. Refuses anything that is not ' +
+        'OData metadata. Read-only on SAP.',
+    // R18: writes a workspace file, so read-only plan-phase subagents must not get it.
+    isMutating: true,
+    requiresSap: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            servicePath: {
+                type: 'string',
+                description: 'Gateway OData path, e.g. /sap/opu/odata/sap/API_BUSINESS_PARTNER or /sap/opu/odata4/sap/<grp>/srvd_a2x/sap/<svc>/0001',
+            },
+            apiName: { type: 'string', description: 'File and model name, e.g. API_BUSINESS_PARTNER' },
+            projectDir: { type: 'string', description: 'CAP project root, relative to the workspace. Default ".".' },
+        },
+        required: ['servicePath', 'apiName'],
+    },
+    handler: (args, ctx) => capMetadataImportHandler(args, ctx),
+});

package/dist/tools/cap/sap-link-tool.js

@@ -0,0 +1,133 @@
+// cspeach-cli/src/tools/cap/sap-link-tool.ts
+//
+// CAP phase 2, Task 8 — `sap_link`: start / stop / status of the SAP link, the
+// loopback forwarder that lets a local CAP app's [s4] profile reach the S/4
+// services it imported, with the developer's stored SAP login.
+//
+// Security posture:
+// - start raises the credential-handover prompt (once per session per alias).
+// - projectDir must resolve inside the workspace (resolveSafePath, then a
+//   realpath check so a linked folder cannot point outside).
+// - Errors are plain: only the registry's own SapLinkError / LinkConfigError
+//   messages pass through. Anything else (keychain, TLS, fs) becomes one fixed
+//   sentence. The password never appears in a result.
+// - status shows url → alias (project) only.
+import * as path from 'node:path';
+import { registerTool, isStandalone } from '../index.js';
+import { resolveSafePath, assertRealPathContained } from '../_filesystem-shared.js';
+import { ensureSapLink, stopSapLink, listSapLinks, SapLinkError } from '../../sap-link/registry.js';
+import { LinkConfigError } from '../../sap-link/project.js';
+const OUTSIDE = 'error: projectDir must be inside the workspace.';
+const fail = (message) => ({ content: `error: ${message}`, is_error: true });
+/** Resolve projectDir inside ctx.cwd, or undefined when it escapes. */
+function safeProjectDir(ctx, projectDir) {
+    try {
+        return resolveSafePath(ctx.cwd, projectDir ?? '.');
+    }
+    catch {
+        return undefined;
+    }
+}
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+/** The workspace-relative path for the handover card, control characters stripped. Undefined when it escapes. */
+function cardPath(ctx, projectDir) {
+    const dir = safeProjectDir(ctx, projectDir);
+    if (!dir)
+        return undefined;
+    const rel = path.relative(path.resolve(ctx.cwd), dir).replace(CONTROL_CHARS, '');
+    return rel === '' ? '.' : rel;
+}
+registerTool({
+    name: 'sap_link',
+    description: 'The SAP link for a local CAP app (CAP phase 2): a forwarder on 127.0.0.1 that lets the app\'s [s4] profile reach ' +
+        'the S/4 services it imported, using the SAP connection CSPeach already has. The password stays in the keychain; ' +
+        'only the services listed in package.json cds.requires ([s4] credentials.url) are reachable; writes pass only when ' +
+        'the alias role is exactly dev. actions: start (projectDir = the CAP project root), stop, status.',
+    isMutating: true,
+    requiresSap: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            action: { type: 'string', enum: ['start', 'stop', 'status'] },
+            projectDir: { type: 'string', description: 'CAP project root, relative to the workspace. Default ".".' },
+        },
+        required: ['action'],
+    },
+    // M-1: the card never shows a raw model-supplied path. An escaping path gets no
+    // card (null); the handler then refuses it. M-2: `scope` keeps this approval
+    // separate from fiori_preview's for the same alias.
+    credentialHandover: (args, ctx) => {
+        if (args.action !== 'start')
+            return null;
+        const shown = cardPath(ctx, args.projectDir);
+        if (shown === undefined)
+            return null;
+        return {
+            alias: ctx.sapAlias,
+            scope: 'sap_link',
+            summary: `Start the SAP link: the CAP app in ${shown} can reach its imported S/4 services on ` +
+                `${ctx.sapAlias} with your stored SAP login. The password stays inside CSPeach.`,
+        };
+    },
+    handler: async (args, ctx) => {
+        if (args.action === 'status') {
+            const all = listSapLinks();
+            return { content: all.length ? all.map((l) => `${l.url} → ${l.alias}  (${l.projectDir})`).join('\n') : 'No SAP link is running.' };
+        }
+        if (args.action !== 'start' && args.action !== 'stop')
+            return fail('action must be start, stop or status.');
+        const dir = safeProjectDir(ctx, args.projectDir);
+        if (!dir)
+            return { content: OUTSIDE, is_error: true };
+        if (args.action === 'stop') {
+            // Start keys the registry by the REAL path (M-3), so stop must too: a junction
+            // then stops the link it started. When the real path can't be read (the folder
+            // was deleted, or a link now points elsewhere), fall back to the resolved path;
+            // stop only ever closes a link this session started.
+            let stopDir = dir;
+            try {
+                stopDir = await assertRealPathContained(dir, ctx.cwd);
+            }
+            catch {
+                stopDir = dir;
+            }
+            return { content: (await stopSapLink(stopDir)) ? 'SAP link stopped.' : 'No SAP link was running for that project.' };
+        }
+        if (isStandalone(ctx))
+            return fail('The SAP link needs a SAP system. This session runs without one.');
+        let realDir;
+        try {
+            // M-3: the real path is the registry key, so a junction and its target share one link.
+            realDir = await assertRealPathContained(dir, ctx.cwd);
+        }
+        catch (e) {
+            const code = e?.code;
+            if (code === 'ENOENT')
+                return fail('projectDir does not exist.');
+            return { content: OUTSIDE, is_error: true };
+        }
+        try {
+            const r = await ensureSapLink(realDir, ctx.sapAlias);
+            const lines = [
+                `SAP link ${r.reused ? 'already on' : 'on'}: ${r.handle.url} → ${ctx.sapAlias}`,
+                `Services: ${r.services.join(', ')}`,
+            ];
+            if (r.roleNote)
+                lines.push(r.roleNote);
+            if (r.tlsNote)
+                lines.push(r.tlsNote);
+            if (r.httpNote)
+                lines.push(r.httpNote);
+            lines.push('Start the app with: cds watch --profile s4');
+            return { content: lines.join('\n') };
+        }
+        catch (e) {
+            if (e instanceof SapLinkError || e instanceof LinkConfigError)
+                return fail(e.message);
+            return fail('The SAP link could not start.');
+        }
+    },
+});