@cspeach/cli 1.1.23 → 1.1.25

package/dist/tools/fiori/apply.js

@@ -5,7 +5,7 @@ import { getEntry } from './catalog/index.js';
 import { renderEntry } from './render.js';
 import { mergeManifest } from './manifest.js';
 import { appendI18n } from './i18n.js';
-import { resolveSafePath } from '../_filesystem-shared.js';
+import { resolveSafePath, assertWritableSync } from '../_filesystem-shared.js';
 /**
  * Render a catalog entry and apply it into an existing scaffolded app on disk.
  *
@@ -15,35 +15,44 @@ import { resolveSafePath } from '../_filesystem-shared.js';
  * CUSTOMER params (e.g. `webapp/ext/fragment/<%- ns %>Chart.fragment.xml`), so a
  * hostile param could otherwise carry `..` and escape `appDir`. Every path this
  * function writes — rendered files, manifest.json, and the i18n file (whose
- * relative location is itself read from on-disk manifest data) — is resolved
- * through `resolveSafePath(opts.appDir, rel)`, which throws PathOutsideRootError
- * if the resolved absolute path is not contained under appDir. This is the
- * authoritative defense; the catalog-side `ns` pattern (render.ts) is the
- * second, earlier layer.
+ * relative location is itself read from on-disk manifest data) — goes through
+ * `resolveSafePath(opts.appDir, rel)` (string containment) and then
+ * `assertWritableSync` (real path after links / short names must stay inside
+ * appDir and must not be a protected path such as a nested `.git`). ALL
+ * targets are checked BEFORE the first write, so a refusal writes nothing.
+ * The catalog-side `ns` pattern (render.ts) is the second, earlier layer.
  */
 export function applyEntry(opts) {
     const rendered = renderEntry(getEntry(opts.entryName), opts.params);
-    // 1. write files — re-validate EVERY rendered (param-derived) path against appDir.
-    for (const f of rendered.files) {
-        const abs = resolveSafePath(opts.appDir, f.path);
-        mkdirSync(dirname(abs), { recursive: true });
-        writeFileSync(abs, f.content, 'utf8');
-    }
-    // 2. merge manifest — ALWAYS re-read from disk (I2). Fixed relative path, but
-    // routed through resolveSafePath for uniform containment.
-    const manifestPath = resolveSafePath(opts.appDir, 'webapp/manifest.json');
+    const denyRoot = opts.denyRoot ?? opts.appDir;
+    const target = (rel) => {
+        const abs = resolveSafePath(opts.appDir, rel);
+        assertWritableSync(abs, opts.appDir, denyRoot);
+        return abs;
+    };
+    // 0. Resolve + verify every write target first.
+    const files = rendered.files.map((f) => ({ abs: target(f.path), content: f.content }));
+    // manifest — ALWAYS re-read from disk (I2). Fixed relative path, still contained.
+    const manifestPath = target('webapp/manifest.json');
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
     let merged = mergeManifest(manifest, rendered.manifestPatch);
     for (const lib of rendered.libraries) {
         merged = mergeManifest(merged, { 'sap.ui5': { dependencies: { libs: { [lib]: {} } } } });
     }
-    writeFileSync(manifestPath, JSON.stringify(merged, null, 2), 'utf8');
-    // 3. append i18n — resolve path from sap.app.i18n (M1). i18nRel is on-disk
-    // data, not a render param, but it still drives a write target, so contain it.
+    // i18n — path from sap.app.i18n (M1): on-disk data that drives a write target.
     const i18nRel = merged['sap.app']?.i18n ?? 'i18n/i18n.properties';
-    const i18nPath = resolveSafePath(opts.appDir, `webapp/${i18nRel}`);
-    const existing = existsSync(i18nPath) ? readFileSync(i18nPath, 'utf8') : '';
-    if (Object.keys(rendered.i18nKeys).length) {
+    const hasI18n = Object.keys(rendered.i18nKeys).length > 0;
+    const i18nPath = hasI18n ? target(`webapp/${i18nRel}`) : null;
+    // 1. write files.
+    for (const f of files) {
+        mkdirSync(dirname(f.abs), { recursive: true });
+        writeFileSync(f.abs, f.content, 'utf8');
+    }
+    // 2. merge manifest.
+    writeFileSync(manifestPath, JSON.stringify(merged, null, 2), 'utf8');
+    // 3. append i18n.
+    if (i18nPath) {
+        const existing = existsSync(i18nPath) ? readFileSync(i18nPath, 'utf8') : '';
         mkdirSync(dirname(i18nPath), { recursive: true });
         writeFileSync(i18nPath, appendI18n(existing, rendered.i18nKeys), 'utf8');
     }

package/dist/tools/fiori/commit-gate.js

@@ -0,0 +1,58 @@
+// cspeach-cli/src/tools/fiori/commit-gate.ts
+/**
+ * Commit-time containment gate for every mem-fs editor the Fiori engine
+ * flushes (scaffoldFreestyle, scaffoldFioriElements, feExtend).
+ *
+ * The @sap-ux writers build paths from caller-supplied config (`folder`,
+ * `name`, `localAnnotationsName`, event-handler file names, …). Validating
+ * each known param is the first layer; THIS is the authoritative one: before
+ * anything reaches disk, every pending path in the editor's store must land —
+ * after following links and expanding Windows short names — inside the app
+ * folder, and must not be a protected path (`.git` at any depth, `.cspeach`,
+ * `.env*`, the CLI home). One bad path refuses the WHOLE commit, so nothing
+ * is half-written.
+ */
+import * as path from 'node:path';
+import { assertWritable, PathOutsideRootError, ProtectedPathError } from '../_filesystem-shared.js';
+/** Thrown when a pending write would leave the app folder or hit a protected path. */
+export class UnsafeCommitError extends Error {
+    constructor(detail) {
+        super(`refusing to write the app: ${detail}. Nothing was written.`);
+        this.name = 'UnsafeCommitError';
+    }
+}
+/** Every path the editor would write or delete on commit. */
+function pendingPaths(editor) {
+    const store = editor.store;
+    if (!store || typeof store.each !== 'function') {
+        // Without a store we cannot see what commit would touch — fail closed.
+        throw new UnsafeCommitError('the pending file list could not be read');
+    }
+    const out = [];
+    store.each((f) => {
+        if (f && (f.state === 'modified' || f.state === 'deleted'))
+            out.push(f.path);
+    });
+    return out;
+}
+/**
+ * Verify every pending path, then commit. `appDir` is the containment root;
+ * `denyRoot` (default appDir) is the project root the denylist is judged
+ * against — tools pass ctx.cwd so a protected folder ABOVE the app is caught.
+ */
+export async function commitContained(editor, appDir, denyRoot = appDir) {
+    for (const p of pendingPaths(editor)) {
+        try {
+            await assertWritable(path.resolve(p), appDir, denyRoot);
+        }
+        catch (err) {
+            const shown = path.relative(path.resolve(denyRoot), path.resolve(p)).replace(/\\/g, '/');
+            if (err instanceof PathOutsideRootError)
+                throw new UnsafeCommitError(`"${shown}" is outside the app folder`);
+            if (err instanceof ProtectedPathError)
+                throw new UnsafeCommitError(`"${shown}" is a protected path`);
+            throw err;
+        }
+    }
+    await new Promise((res, rej) => editor.commit((e) => (e ? rej(e) : res())));
+}

package/dist/tools/fiori/fe-extend.js

@@ -16,6 +16,8 @@
  */
 import { create } from 'mem-fs';
 import { create as createEditor } from 'mem-fs-editor';
+import { commitContained } from './commit-gate.js';
+import { assertFeExtendParams } from './path-params.js';
 /** The four supported extension operations. Closed union → schema enum. */
 export const FE_EXTEND_OPS = ['custom-column', 'custom-action', 'custom-section', 'controller-extension'];
 /** Thrown when the target app is not a V4 Fiori Elements app (no sap.fe.templates). */
@@ -52,6 +54,9 @@ export function withActionHandler(params) {
     return { ...params, settings, eventHandler };
 }
 export async function feExtend(opts) {
+    // Path-shaped params first (name / folder / handler fileName): no `..`, no
+    // absolute paths, no drive letters. The commit gate below is the backstop.
+    assertFeExtendParams(opts.params);
     // Dynamic import: keep the heavy writer out of the cold-start path (mirrors
     // the engine's lazy-load convention; only paid when the tool actually runs).
     const fpm = await import('@sap-ux/fe-fpm-writer');
@@ -87,5 +92,5 @@ export async function feExtend(opts) {
             throw new NotV4FeAppError();
         throw err;
     }
-    await new Promise((res, rej) => result.commit((e) => (e ? rej(e) : res())));
+    await commitContained(result, opts.basePath, opts.denyRoot ?? opts.basePath);
 }

package/dist/tools/fiori/fe-scaffold.js

@@ -2,6 +2,8 @@ import { create } from 'mem-fs';
 import { create as createEditor } from 'mem-fs-editor';
 import { join } from 'node:path';
 import { PINNED_UI5_VERSION } from './ui5-version.js';
+import { commitContained } from './commit-gate.js';
+import { assertPlainName } from './path-params.js';
 // The ONE pinned, CDN-hosted patch (ui5-version.ts) — never an x.y.0 guess.
 const DEFAULT_UI5_VERSION = PINNED_UI5_VERSION;
 /**
@@ -102,6 +104,9 @@ function loadListsOnOpen(fs, manifestPath, ui5Version) {
 export async function scaffoldFioriElements(opts) {
     // Loaded on use (fix round 3, item 11e): this writer's module graph alone
     // cost ~2.8 s of every CLI start, Fiori work or not.
+    // technicalName becomes webapp/annotations/<name>.xml — a plain name only.
+    if (opts.localAnnotations)
+        assertPlainName('localAnnotations.technicalName', opts.localAnnotations.technicalName);
     const { generate, TemplateType, OdataVersion } = await import('@sap-ux/fiori-elements-writer');
     const ui5Version = opts.ui5Version ?? DEFAULT_UI5_VERSION;
     const version = opts.service.version === '2.0' ? OdataVersion.v2 : OdataVersion.v4;
@@ -194,5 +199,5 @@ export async function scaffoldFioriElements(opts) {
     if (opts.localAnnotations) {
         fs.write(join(opts.basePath, 'webapp', 'annotations', `${opts.localAnnotations.technicalName}.xml`), opts.localAnnotations.xml);
     }
-    await new Promise((res, rej) => fs.commit((err) => (err ? rej(err) : res())));
+    await commitContained(fs, opts.basePath, opts.denyRoot ?? opts.basePath);
 }

package/dist/tools/fiori/path-params.js

@@ -0,0 +1,78 @@
+// cspeach-cli/src/tools/fiori/path-params.ts
+/**
+ * Validation for caller-supplied values the @sap-ux writers turn into file
+ * paths (fe_extend `name` / `folder` / event-handler `fileName`, scaffold_fe
+ * `localAnnotations.technicalName`). First layer only — commit-gate.ts is the
+ * authoritative check on the final paths.
+ */
+import { isWindowsReservedName } from '../_filesystem-shared.js';
+/** Thrown for a path-shaped param that could leave the app folder. */
+export class UnsafePathParamError extends Error {
+    constructor(label, value, why) {
+        super(`${label} ${JSON.stringify(value)} is not allowed: ${why}`);
+        this.name = 'UnsafePathParamError';
+    }
+}
+/** A single name segment: no separators, no `..`, no `:`, no NUL, no trailing dot/space. */
+function badSegment(seg) {
+    if (seg.length === 0)
+        return 'empty name';
+    if (seg === '.' || seg === '..' || seg.includes('..'))
+        return 'no ".." allowed';
+    if (seg.includes(':'))
+        return 'no ":" allowed';
+    if (seg.includes('\0'))
+        return 'no NUL allowed';
+    if (/[. ]$/.test(seg))
+        return 'must not end with a dot or space';
+    if (/[<>"|?*\u0000-\u001f]/.test(seg))
+        return 'contains a character not allowed in file names';
+    if (isWindowsReservedName(seg))
+        return 'is a reserved Windows device name (CON, PRN, AUX, NUL, COM0-9, LPT0-9)';
+    return null;
+}
+/** A plain file/folder name: one segment, no separators. */
+export function assertPlainName(label, value) {
+    if (typeof value !== 'string')
+        throw new UnsafePathParamError(label, value, 'must be a string');
+    if (value.includes('/') || value.includes('\\'))
+        throw new UnsafePathParamError(label, value, 'must be a plain name, no folders');
+    const why = badSegment(value);
+    if (why)
+        throw new UnsafePathParamError(label, value, why);
+}
+/**
+ * A relative sub-folder (`ext/sections`): '/'-separated plain segments.
+ * Not absolute, no backslashes, no drive letters, no `..` anywhere.
+ */
+export function assertRelativeSubfolder(label, value) {
+    if (typeof value !== 'string')
+        throw new UnsafePathParamError(label, value, 'must be a string');
+    if (value.includes('\\'))
+        throw new UnsafePathParamError(label, value, 'use "/" between folders');
+    if (value.startsWith('/'))
+        throw new UnsafePathParamError(label, value, 'must be relative to the app');
+    const segs = value.replace(/\/+$/, '').split('/');
+    for (const seg of segs) {
+        const why = badSegment(seg);
+        if (why)
+            throw new UnsafePathParamError(label, value, why);
+    }
+}
+/**
+ * fe_extend params: `name` (plain), `folder` (relative sub-folder), and an
+ * event handler's `fileName` (top level or under settings) — a sub-folder
+ * path is allowed there too, still with no `..`.
+ */
+export function assertFeExtendParams(params) {
+    if (params.name !== undefined)
+        assertPlainName('name', params.name);
+    if (params.folder !== undefined)
+        assertRelativeSubfolder('folder', params.folder);
+    const handlers = [params.eventHandler, params.settings?.eventHandler];
+    for (const h of handlers) {
+        if (h && typeof h === 'object' && h.fileName !== undefined) {
+            assertRelativeSubfolder('eventHandler.fileName', h.fileName);
+        }
+    }
+}

package/dist/tools/fiori/scaffold.js

@@ -4,6 +4,7 @@ import { create as createEditor } from 'mem-fs-editor';
 import { join } from 'node:path';
 import { PINNED_UI5_VERSION } from './ui5-version.js';
 import { decodePropertiesValues } from './html-escapes.js';
+import { commitContained } from './commit-gate.js';
 // Without an explicit ui5 config the writer falls back to minUI5Version 1.60,
 // which fiori-tools-proxy resolves to the 1.71 LTS — whose bootstrap does NOT
 // understand the hyphenated `data-sap-ui-on-init` attribute the writer itself
@@ -47,5 +48,5 @@ export async function scaffoldFreestyle(opts) {
     const i18nPath = join(opts.basePath, 'webapp', 'i18n', 'i18n.properties');
     if (fs.exists(i18nPath))
         fs.write(i18nPath, decodePropertiesValues(fs.read(i18nPath)));
-    await new Promise((res, rej) => fs.commit((err) => (err ? rej(err) : res())));
+    await commitContained(fs, opts.basePath, opts.denyRoot ?? opts.basePath);
 }

package/dist/tools/fiori/tools.js

@@ -47,7 +47,7 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
-import { resolveSafePath, PathOutsideRootError } from '../_filesystem-shared.js';
+import { resolveSafePath, realPathForWrite, isDenylistedPath, PathOutsideRootError, DENYLIST_DESCRIPTION, } from '../_filesystem-shared.js';
 import { scaffoldFreestyle } from './scaffold.js';
 import { decodeHtmlEscapes } from './html-escapes.js';
 import { applyEntry } from './apply.js';
@@ -80,16 +80,53 @@ const SAMPLE_INDEX = sampleIndexJson;
 // model can cite the source (licensing constraint A-M1). Derived from the
 // corpus NOTICE: OpenUI5 sources, adapted, under Apache-2.0.
 const SAMPLE_ATTRIBUTION = 'Adapted from OpenUI5 (github.com/SAP/openui5) sample sources, licensed under Apache-2.0.';
-/** Resolve a user-supplied dir inside the project root, mapping the escape error. */
-function safeDir(ctx, userPath) {
+/** Shared denylist refusal text for a protected app / base folder. */
+function protectedDirError(p, ctx) {
+    const verdict = isDenylistedPath(p, ctx.cwd);
+    return verdict.blocked
+        ? `"${verdict.relFromRoot}" is a protected folder (denylist: ${DENYLIST_DESCRIPTION})`
+        : null;
+}
+/**
+ * Sync form of safeDir for pure read helpers: containment + the shared
+ * denylist on the spelled path (which already covers NTFS stream suffixes,
+ * trailing dots/spaces and 8.3 short names). No link resolution.
+ */
+function safeDirSync(ctx, userPath) {
+    let abs;
+    try {
+        abs = resolveSafePath(ctx.cwd, userPath);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError)
+            return { error: err.message };
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    const refused = protectedDirError(abs, ctx);
+    return refused ? { error: refused } : { abs };
+}
+/**
+ * Resolve a user-supplied dir inside the project root, mapping the escape error.
+ * The dir must also not be a protected folder (`.git`, `.cspeach`, …) or an
+ * alias of one — checked on the spelled path AND on its real path (links,
+ * Windows 8.3 short names), through the shared denylist. The returned `abs` is
+ * still the spelled path so result strings and registry keys stay unchanged.
+ */
+async function safeDir(ctx, userPath) {
+    const spelled = safeDirSync(ctx, userPath);
+    if ('error' in spelled)
+        return spelled;
+    let real;
     try {
-        return { abs: resolveSafePath(ctx.cwd, userPath) };
+        real = await realPathForWrite(spelled.abs, ctx.cwd);
     }
     catch (err) {
         if (err instanceof PathOutsideRootError)
             return { error: err.message };
         return { error: err instanceof Error ? err.message : String(err) };
     }
+    const refused = protectedDirError(real, ctx);
+    return refused ? { error: refused } : spelled;
 }
 /** Relative-to-cwd, forward-slash path for stable, readable result strings. */
 function rel(ctx, abs) {
@@ -127,11 +164,12 @@ export async function fioriScaffoldHandler(args, ctx) {
         return { content: 'error: basePath is required', is_error: true };
     if (!args.appId)
         return { content: 'error: appId is required', is_error: true };
-    const resolved = safeDir(ctx, args.basePath);
+    const resolved = await safeDir(ctx, args.basePath);
     if ('error' in resolved)
         return { content: `error: ${resolved.error}`, is_error: true };
     try {
         await scaffoldFreestyle({
+            denyRoot: ctx.cwd,
             basePath: resolved.abs,
             appId: args.appId,
             appTitle: decodeTitle(args.appTitle ?? args.appId),
@@ -160,7 +198,7 @@ export async function fioriApplyHandler(args, ctx) {
         return { content: 'error: appDir is required', is_error: true };
     if (!args.entry)
         return { content: 'error: entry is required', is_error: true };
-    const resolved = safeDir(ctx, args.appDir);
+    const resolved = await safeDir(ctx, args.appDir);
     if ('error' in resolved)
         return { content: `error: ${resolved.error}`, is_error: true };
     // Params may arrive as a parsed object (preferred) or a JSON string (mirrors
@@ -181,7 +219,7 @@ export async function fioriApplyHandler(args, ctx) {
         // applyEntry preserves the engine's loud-on-conflict manifest merge — a
         // conflicting manifest patch throws here and surfaces as is_error, never a
         // silent last-wins overwrite.
-        applyEntry({ appDir: resolved.abs, entryName: args.entry, params });
+        applyEntry({ appDir: resolved.abs, entryName: args.entry, params, denyRoot: ctx.cwd });
     }
     catch (err) {
         return { content: `error: apply failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
@@ -210,7 +248,7 @@ export async function fioriDeployConfigHandler(args, ctx) {
         return { content: 'error: name (BSP app name) is required', is_error: true };
     if (!args.package)
         return { content: 'error: package is required', is_error: true };
-    const resolved = safeDir(ctx, args.appDir);
+    const resolved = await safeDir(ctx, args.appDir);
     if ('error' in resolved)
         return { content: `error: ${resolved.error}`, is_error: true };
     try {
@@ -248,11 +286,12 @@ export async function fioriScaffoldFeHandler(args, ctx) {
         return { content: 'error: localAnnotations requires both technicalName and xml', is_error: true };
     }
     // metadata is OPTIONAL (the FE writer does not need it — spike §4); no $metadata fetch.
-    const resolved = safeDir(ctx, args.basePath);
+    const resolved = await safeDir(ctx, args.basePath);
     if ('error' in resolved)
         return { content: `error: ${resolved.error}`, is_error: true };
     try {
         await scaffoldFioriElements({
+            denyRoot: ctx.cwd,
             basePath: resolved.abs,
             appId: args.appId,
             appTitle: decodeTitle(args.appTitle ?? args.appId),
@@ -284,12 +323,12 @@ export async function feExtendHandler(args, ctx) {
     if (!FE_EXTEND_OPS.includes(args.op)) {
         return { content: `error: unknown op "${args.op}" — expected one of ${FE_EXTEND_OPS.join(', ')}`, is_error: true };
     }
-    const resolved = safeDir(ctx, args.basePath);
+    const resolved = await safeDir(ctx, args.basePath);
     if ('error' in resolved)
         return { content: `error: ${resolved.error}`, is_error: true };
     const before = new Set(await listFilesUnder(ctx, resolved.abs));
     try {
-        await feExtend({ basePath: resolved.abs, op: args.op, params: args.params ?? {} });
+        await feExtend({ basePath: resolved.abs, op: args.op, params: args.params ?? {}, denyRoot: ctx.cwd });
     }
     catch (err) {
         // V4-only scope limit: fe-fpm-writer refuses non-V4-FE apps (no
@@ -369,7 +408,7 @@ export async function fioriPreviewHandler(args, ctx, deps) {
     }
     if (!args.appDir)
         return { content: 'error: appDir is required for action "start"', is_error: true };
-    const resolved = safeDir(ctx, args.appDir);
+    const resolved = await safeDir(ctx, args.appDir);
     if ('error' in resolved)
         return { content: `error: ${resolved.error}`, is_error: true };
     const result = await startPreview({
@@ -442,7 +481,7 @@ export function resolvePreviewAppUrl(args) {
  * without launching a browser; the handler only orchestrates.
  */
 export function resolveFreestyleSmokeSpec(args, ctx) {
-    const resolved = safeDir(ctx, args.appDir);
+    const resolved = safeDirSync(ctx, args.appDir);
     if ('error' in resolved)
         return { error: resolved.error };
     let derived;
@@ -1233,7 +1272,7 @@ registerTool({
         try {
             if (!args.appDir)
                 return handover;
-            const resolved = safeDir(ctx, args.appDir);
+            const resolved = await safeDir(ctx, args.appDir);
             if ('error' in resolved)
                 return handover;
             const startScript = await readStartScript(resolved.abs);