@cspeach/cli 1.1.22 → 1.1.24

package/dist/sap-link/upstream.js

@@ -0,0 +1,367 @@
+// cspeach-cli/src/sap-link/upstream.ts
+/**
+ * CAP phase 2 — the SAP link's one upstream session to SAP Gateway (spec §6.3).
+ *
+ * It adds the developer's SAP login (basic auth) and the sap-client, keeps its own
+ * cookie jar and CSRF token (separate from the ADT connection, whose token belongs to
+ * a different ICF service), and fetches the token before a write with one retry.
+ * The password lives only in this object, in this process. Nothing here logs.
+ *
+ * Layering: policy.ts is the PRIMARY gate (service allowlist, dev-only writes,
+ * tunnelling and encoding refusals). This module is the BACKSTOP: it re-checks what it
+ * can cheaply and never trusts that the caller already did.
+ *
+ * Hardening choices (Task 6 security requirements + fix round 1):
+ *   - Only GET, HEAD, POST, PUT, PATCH, MERGE and DELETE are sent (upper-cased first).
+ *     Anything else (TRACE can echo the Authorization header; CONNECT hangs) is refused
+ *     with EBADMETHOD before a byte goes out.
+ *   - Incoming headers the app may not set are dropped case-insensitively: login,
+ *     cookies, token, hop-by-hop / framing headers, method tunnelling, forwarding
+ *     headers, every `sap-*` header except `sap-language`, and every `x-sap-*`.
+ *   - sap-client is FORCED: every `sap-*` query parameter except `sap-language` (decoded
+ *     name, any case) is removed, and the configured sap-client appended. The rest of the query is kept byte-for-byte,
+ *     never re-encoded, so OData `$filter` text reaches SAP unchanged.
+ *   - GET and HEAD never carry a body.
+ *   - Response headers that carry session, token, login challenge or framing are never
+ *     returned, nor any header whose value contains the login (paranoid check).
+ *   - The response body is capped (64 MiB default) → ERESPONSETOOLARGE. One overall
+ *     deadline (60 s default) covers the whole exchange → ETIMEDOUT. Redirects are
+ *     never followed (Node's http does not, and we add nothing that does).
+ *   - The base URL must be http: or https:. https uses its own Agent with
+ *     `rejectUnauthorized` and `ca` from config; NODE_TLS_REJECT_UNAUTHORIZED is never
+ *     touched. The request goes to the configured host only: the path must be a plain
+ *     absolute path (no `//host`, scheme, `#`, backslash, whitespace or control chars),
+ *     and the only matrix parameter allowed in it is `;v=<digits>` (service version).
+ *   - The cookie jar stores name=value only (attributes ignored), a later cookie of the
+ *     same name replaces the earlier one, malformed cookies are dropped, and the jar is
+ *     bounded. A cookie set to an empty value, `Max-Age<=0` or a past `Expires` is
+ *     deleted from the jar.
+ *   - close() destroys the agent and clears cookies and token; send() after close()
+ *     throws ECLOSED without sending.
+ *   - 401 latch (final wave): after the first 401 from SAP (any request, including the
+ *     CSRF token fetch) every later send throws ELOGINREJECTED WITHOUT sending, until
+ *     the link restarts (a new UpstreamSession). Repeated Basic-auth retries with a
+ *     stale password can lock the developer's SAP user. Requests already in flight
+ *     when the first 401 arrives are not recalled.
+ */
+import * as http from 'node:http';
+import * as https from 'node:https';
+const DEFAULT_MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_COOKIES = 50;
+/**
+ * The bare password is only scanned for in response headers when it has 4 or more
+ * characters: a 1-3 char string would match unrelated headers (content-type etc.).
+ * The full `Basic …` string and the base64 credential are ALWAYS scanned, so the
+ * login itself is covered whatever the password length.
+ */
+const MIN_PASSWORD_SCAN_LEN = 4;
+/** Request headers the app may NOT set upstream — the link owns login, session and token. */
+const DROP_IN = new Set([
+    'authorization', 'proxy-authorization', 'cookie', 'host', 'x-csrf-token',
+    'connection', 'keep-alive', 'content-length', 'transfer-encoding', 'te', 'upgrade',
+    'expect', 'trailer', 'x-http-method', 'x-http-method-override', 'forwarded',
+]);
+function dropIncoming(lower) {
+    if (DROP_IN.has(lower))
+        return true;
+    if (lower.startsWith('x-forwarded-'))
+        return true;
+    if (lower.startsWith('x-sap-'))
+        return true;
+    if (lower.startsWith('sap-') && lower !== 'sap-language')
+        return true;
+    return false;
+}
+/** Response headers never handed back to the app. */
+const DROP_OUT = new Set([
+    'set-cookie', 'set-cookie2', 'x-csrf-token', 'connection', 'keep-alive',
+    'transfer-encoding', 'content-length', 'www-authenticate', 'proxy-authenticate',
+]);
+/** RFC 7230 token — valid cookie names. */
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** RFC 6265 cookie-octets (quotes allowed around the whole value). */
+const COOKIE_VALUE = /^"?[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]*"?$/;
+function codedError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+/** A plain absolute path on the configured host — nothing that can change the target. */
+function assertPlainPath(p, what) {
+    if (!p.startsWith('/') || p.startsWith('//') || /[\\#\s\x00-\x1f\x7f]/.test(p)) {
+        throw codedError(`Upstream ${what} is not a plain absolute path.`, 'EBADPATH');
+    }
+    // The only matrix parameter allowed in the path is the service version `;v=<digits>`
+    // (e.g. `API_X;v=0002`). `;sap-client=…`, `;o=…` and the like are refused.
+    const q = p.indexOf('?');
+    const pathname = q < 0 ? p : p.slice(0, q);
+    if (pathname.replace(/;v=\d+(?=\/|$)/g, '').includes(';')) {
+        throw codedError(`Upstream ${what} has a matrix parameter that is not allowed.`, 'EBADPATH');
+    }
+}
+const ALLOWED_METHOD = /^(GET|HEAD|POST|PUT|PATCH|MERGE|DELETE)$/;
+/** True when a Set-Cookie line says the cookie is already gone (Max-Age<=0 or past Expires). */
+function isExpired(setCookie) {
+    let maxAge;
+    let expires;
+    for (const a of setCookie.split(';').slice(1)) {
+        const i = a.indexOf('=');
+        const k = (i < 0 ? a : a.slice(0, i)).trim().toLowerCase();
+        const v = i < 0 ? '' : a.slice(i + 1).trim();
+        if (k === 'max-age' && /^-?\d+$/.test(v))
+            maxAge = Number(v);
+        else if (k === 'expires') {
+            const t = Date.parse(v);
+            if (!Number.isNaN(t))
+                expires = t;
+        }
+    }
+    if (maxAge !== undefined)
+        return maxAge <= 0; // Max-Age wins over Expires (RFC 6265 §5.3)
+    return expires !== undefined && expires <= Date.now();
+}
+/**
+ * One upstream session to SAP Gateway for the SAP link (spec §6.3). Its own cookie
+ * jar and CSRF token. The password lives only in `this.auth`, in this process.
+ */
+export class UpstreamSession {
+    cfg;
+    auth;
+    secrets;
+    agent;
+    isHttps;
+    host;
+    port;
+    maxResponseBytes;
+    timeoutMs;
+    cookies = new Map();
+    token = '';
+    tokenInFlight;
+    closed = false;
+    /** Set by the first upstream 401; never cleared (a restart builds a new session). */
+    loginRejected = false;
+    constructor(cfg, opts = {}) {
+        this.cfg = cfg;
+        let u;
+        try {
+            u = new URL(cfg.baseUrl);
+        }
+        catch {
+            throw codedError('SAP base URL is not a valid URL.', 'EBADURL');
+        }
+        if (u.protocol !== 'https:' && u.protocol !== 'http:') {
+            throw codedError('SAP base URL must use http or https.', 'EBADURL');
+        }
+        this.isHttps = u.protocol === 'https:';
+        this.host = u.hostname.replace(/^\[(.*)\]$/, '$1');
+        this.port = u.port ? Number(u.port) : undefined;
+        const cred = Buffer.from(`${cfg.username}:${cfg.password}`).toString('base64');
+        this.auth = 'Basic ' + cred;
+        this.secrets = [this.auth.toLowerCase(), cred.toLowerCase()];
+        if (cfg.password.length >= MIN_PASSWORD_SCAN_LEN)
+            this.secrets.push(cfg.password.toLowerCase());
+        this.agent = this.isHttps
+            ? new https.Agent({ keepAlive: true, rejectUnauthorized: cfg.rejectUnauthorized, ...(cfg.ca ? { ca: cfg.ca } : {}) })
+            : new http.Agent({ keepAlive: true });
+        this.maxResponseBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** True once SAP answered 401: this session sends nothing more (the link must restart). */
+    isLoginRejected() {
+        return this.loginRejected;
+    }
+    /** Drop the connections, cookies and token. Later send() calls throw ECLOSED. */
+    close() {
+        this.closed = true;
+        this.agent.destroy();
+        this.cookies.clear();
+        this.token = '';
+    }
+    async send(req) {
+        if (this.closed)
+            throw codedError('Upstream session is closed.', 'ECLOSED');
+        const method = typeof req.method === 'string' ? req.method.toUpperCase() : '';
+        if (!ALLOWED_METHOD.test(method))
+            throw codedError('Upstream method is not allowed.', 'EBADMETHOD');
+        assertPlainPath(req.path, 'path');
+        if (req.write)
+            assertPlainPath(req.servicePrefix, 'service prefix');
+        if (req.write && !this.token)
+            await this.fetchToken(req.servicePrefix);
+        let res = await this.raw(method, req.path, this.outHeaders(req), req.body);
+        if (req.write && res.status === 403 && isRequired(res.rawHeaders['x-csrf-token'])) {
+            // One refetch + one retry. A second failure goes back to the app as-is.
+            this.token = '';
+            await this.fetchToken(req.servicePrefix);
+            res = await this.raw(method, req.path, this.outHeaders(req), req.body);
+        }
+        return { status: res.status, headers: this.inHeaders(res.rawHeaders), body: res.body };
+    }
+    outHeaders(req) {
+        const h = {};
+        for (const [k, v] of Object.entries(req.headers)) {
+            const lower = k.toLowerCase();
+            if (typeof v !== 'string' || dropIncoming(lower))
+                continue;
+            h[lower] = v;
+        }
+        if (req.write && this.token)
+            h['x-csrf-token'] = this.token;
+        return h;
+    }
+    inHeaders(raw) {
+        const out = {};
+        for (const [k, v] of Object.entries(raw)) {
+            const lower = k.toLowerCase();
+            if (v === undefined || DROP_OUT.has(lower))
+                continue;
+            const value = Array.isArray(v) ? v.join(', ') : String(v);
+            const lv = value.toLowerCase();
+            if (this.secrets.some((s) => lv.includes(s)))
+                continue;
+            out[lower] = value;
+        }
+        return out;
+    }
+    fetchToken(servicePrefix) {
+        if (!this.tokenInFlight) {
+            this.tokenInFlight = (async () => {
+                const res = await this.raw('GET', `${servicePrefix.replace(/\/+$/, '')}/`, { 'x-csrf-token': 'Fetch', accept: 'application/json' }, Buffer.alloc(0));
+                if (res.status === 401)
+                    throw loginRejectedError();
+                const t = res.rawHeaders['x-csrf-token'];
+                const value = Array.isArray(t) ? t[0] : t;
+                this.token = value && !isRequired(value) ? String(value) : '';
+            })().finally(() => { this.tokenInFlight = undefined; });
+        }
+        return this.tokenInFlight;
+    }
+    /**
+     * Remove every `sap-*` query parameter except `sap-language` (decoded name, any case)
+     * and append the configured sap-client. Other segments are kept byte-for-byte.
+     */
+    withClient(p) {
+        const q = p.indexOf('?');
+        const pathname = q < 0 ? p : p.slice(0, q);
+        const query = q < 0 ? '' : p.slice(q + 1);
+        const kept = query.split('&').filter((seg) => {
+            if (seg === '')
+                return false;
+            const eq = seg.indexOf('=');
+            const rawName = eq < 0 ? seg : seg.slice(0, eq);
+            let name = rawName;
+            try {
+                name = decodeURIComponent(rawName.replace(/\+/g, ' '));
+            }
+            catch { /* keep raw name */ }
+            const lower = name.trim().toLowerCase();
+            return !lower.startsWith('sap-') || lower === 'sap-language';
+        });
+        kept.push(`sap-client=${encodeURIComponent(this.cfg.client)}`);
+        return `${pathname}?${kept.join('&')}`;
+    }
+    storeCookies(setCookie) {
+        for (const c of setCookie ?? []) {
+            const pair = c.split(';', 1)[0] ?? '';
+            const i = pair.indexOf('=');
+            if (i <= 0)
+                continue;
+            const name = pair.slice(0, i).trim();
+            const value = pair.slice(i + 1).trim();
+            if (!COOKIE_NAME.test(name))
+                continue;
+            if (value === '' || value === '""' || isExpired(c)) {
+                this.cookies.delete(name);
+                continue;
+            }
+            if (!COOKIE_VALUE.test(value))
+                continue;
+            if (!this.cookies.has(name) && this.cookies.size >= MAX_COOKIES)
+                continue;
+            this.cookies.set(name, value);
+        }
+    }
+    raw(method, p, headers, body) {
+        if (this.closed)
+            return Promise.reject(codedError('Upstream session is closed.', 'ECLOSED'));
+        if (this.loginRejected)
+            return Promise.reject(loginRejectedError());
+        const noBody = /^(GET|HEAD)$/i.test(method);
+        const all = { ...headers, authorization: this.auth };
+        if (!noBody)
+            all['content-length'] = String(body.length);
+        if (this.cookies.size)
+            all.cookie = [...this.cookies].map(([k, v]) => `${k}=${v}`).join('; ');
+        const lib = this.isHttps ? https : http;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let r;
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+                // Destroy WITHOUT the error: we already rejected, and destroy(err) re-emits it
+                // on streams that may have no listener left (uncaught exception).
+                r?.destroy();
+            };
+            const timer = setTimeout(() => fail(codedError('upstream timeout', 'ETIMEDOUT')), this.timeoutMs);
+            try {
+                r = lib.request({
+                    protocol: this.isHttps ? 'https:' : 'http:',
+                    host: this.host,
+                    ...(this.port !== undefined ? { port: this.port } : {}),
+                    path: this.withClient(p),
+                    method,
+                    headers: all,
+                    agent: this.agent,
+                }, (res) => {
+                    // Listeners first: fail() destroys the request, which errors `res`.
+                    res.on('error', fail);
+                    res.on('aborted', () => fail(codedError('upstream connection closed', 'ECONNRESET')));
+                    // Latch as soon as the status is known, even if the body later fails.
+                    if (res.statusCode === 401)
+                        this.loginRejected = true;
+                    this.storeCookies(res.headers['set-cookie']);
+                    const declared = Number(res.headers['content-length']);
+                    if (Number.isFinite(declared) && declared > this.maxResponseBytes) {
+                        return fail(codedError('upstream response too large', 'ERESPONSETOOLARGE'));
+                    }
+                    const chunks = [];
+                    let total = 0;
+                    res.on('data', (d) => {
+                        if (settled)
+                            return;
+                        total += d.length;
+                        if (total > this.maxResponseBytes)
+                            return fail(codedError('upstream response too large', 'ERESPONSETOOLARGE'));
+                        chunks.push(d);
+                    });
+                    res.on('end', () => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        clearTimeout(timer);
+                        resolve({ status: res.statusCode ?? 0, rawHeaders: res.headers, body: Buffer.concat(chunks) });
+                    });
+                });
+            }
+            catch (err) {
+                fail(err instanceof Error ? err : new Error('upstream request failed'));
+                return;
+            }
+            r.on('error', fail);
+            if (noBody)
+                r.end();
+            else
+                r.end(body);
+        });
+    }
+}
+function loginRejectedError() {
+    return codedError('SAP rejected the stored login; nothing more is sent until the link restarts.', 'ELOGINREJECTED');
+}
+function isRequired(v) {
+    const s = Array.isArray(v) ? v[0] : v;
+    return typeof s === 'string' && s.trim().toLowerCase() === 'required';
+}

package/dist/sap-link/write-log.js

@@ -0,0 +1,60 @@
+// cspeach-cli/src/sap-link/write-log.ts
+/**
+ * CAP phase 2 — the SAP link's write log. One JSON line per forwarded write:
+ * time, method, path (entity key included, query removed), status. Never headers,
+ * never bodies, never the login.
+ *
+ * status 0 means "outcome unknown": the write was sent but no answer came back
+ * (timeout, reset, any upstream error). SAP may or may not have applied it (ruling R16).
+ *
+ * Only the path is run through scrubSecrets (the only field that can carry request
+ * text). The row is built from the clean fields AFTER scrubbing, so a short or numeric
+ * password (e.g. "2026") can never corrupt `at`, `method` or `status`.
+ *
+ * The directory is created 0700 and the file 0600, and on POSIX both are chmod-ed to
+ * those modes after every append (best effort) so an existing loose file is tightened.
+ * On Windows modes are skipped; the file lives under the user's own profile.
+ */
+import { appendFileSync, chmodSync, mkdirSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { scrubSecrets } from '../tools/fiori/preview/env.js';
+/** One line per forwarded write: time, method, path (entity key included), status. No headers, no bodies. */
+export function appendWriteRow(file, row, secret) {
+    const dir = path.dirname(file);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Only these four fields, whatever else the caller's object carries. Query dropped defensively.
+    const clean = {
+        at: String(row.at),
+        method: String(row.method),
+        path: scrubSecrets(String(row.path).split(/[?#]/, 1)[0], secret.password, secret.username),
+        status: Number(row.status),
+    };
+    appendFileSync(file, JSON.stringify(clean) + '\n', { encoding: 'utf8', mode: 0o600 });
+    if (process.platform !== 'win32') {
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch { /* best effort */ }
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch { /* best effort */ }
+    }
+}
+export function readWriteRows(file, sinceIso) {
+    let text = '';
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    return text.split('\n').filter(Boolean).flatMap((l) => {
+        try {
+            return [JSON.parse(l)];
+        }
+        catch {
+            return [];
+        }
+    }).filter((r) => !sinceIso || r.at >= sinceIso);
+}

package/dist/skill-catalog.js

@@ -1,12 +1,13 @@
 /**
  * Static skill catalog for CSPeach CLI v0.2.
  *
- * STALENESS RISK (spec §3.3): This constant is hardcoded against the 33 skills
+ * STALENESS RISK (spec §3.3): This constant is hardcoded against the 35 skills
  * in .claude/skills/ as of 2026-07-03 (abap-dump-analyze + abap-dump-triage
  * merged into abap-dump 2026-06-12; abap-extend-model added 2026-06-25;
  * abap-radar/abap-document/abap-performance/abap-cloud-check merged into
  * abap-explain/abap-handover/abap-review 2026-06-28 per
- * plan 2026-06-28-skill-portfolio-merge; abap-clean-core added 2026-06-29). It will drift if skills are added or
+ * plan 2026-06-28-skill-portfolio-merge; abap-clean-core added 2026-06-29; abap-cap added
+ * 2026-09-25; abap-app added 2026-10-01). It will drift if skills are added or
  * removed. At Plan 4b kickoff decision the build-time generation option
  * (scripts/generate-skill-catalog.ts reads SKILL.md frontmatter) or runtime
  * fetch (/v1/skills endpoint) will be chosen to replace this file. Until then,
@@ -109,11 +110,18 @@ export const SKILL_CATALOG = [
     {
         name: 'abap-segw',
         category: 'Modify / Fix',
-        description: 'Implement SEGW OData DPC_EXT method bodies — reads generated MPC/DPC base classes. SEGW project itself created in transaction SEGW. For S/4 1909+ RAP services use /abap-rap.',
-        whenToUse: `pick this for DPC_EXT method bodies on an EXISTING SEGW project (ECC / older S/4; not /abap-rap — that's S/4 1909+ RAP; SEGW project + MPC/DPC must already exist)`,
+        description: 'Implement SEGW OData DPC_EXT method bodies — reads generated MPC/DPC base classes. SEGW project itself created in transaction SEGW. For S/4 2020+ RAP services use /abap-rap.',
+        whenToUse: `pick this for DPC_EXT method bodies on an EXISTING SEGW project (ECC / older S/4; not /abap-rap — that's S/4 2020+ RAP; SEGW project + MPC/DPC must already exist)`,
         asks: 'which project and operation? e.g. "GET_ENTITYSET for ZORDER_SRV"',
     },
     // ── Create / Generate ────────────────────────────────────────────────────
+    {
+        name: 'abap-app',
+        category: 'Create / Generate',
+        description: 'One entry from a spec (Word, PDF, Excel or text) to a running app — spec gaps, then the app lane (backend + UI, picked by the CLI and confirmed on the lane card), then the plan and the build.',
+        whenToUse: `pick this to build an app FROM a spec document (not /abap-rap or /abap-cap — those build one stack you already chose)`,
+        asks: 'the spec file. e.g. "@specs/inspection-log.docx"',
+    },
     {
         name: 'abap-generate',
         category: 'Create / Generate',
@@ -124,8 +132,8 @@ export const SKILL_CATALOG = [
     {
         name: 'abap-rap',
         category: 'Create / Generate',
-        description: 'Scaffold a complete RAP stack on S/4HANA 1909+ — table, CDS interface, projection, BDEF, BP class, SRVD, SRVB, DDLX, DCL. ECC/older S/4 → use /abap-segw.',
-        whenToUse: `pick this for a full RAP stack on S/4 1909+ (10 objects, table → SRVB; not /abap-segw — that's ECC/older S/4 OData; not /abap-generate — that's one object)`,
+        description: 'Scaffold a complete RAP stack on S/4HANA 2020+ — table, CDS interface, projection, BDEF, BP class, SRVD, SRVB, DDLX, DCL. ECC/older S/4 → use /abap-segw.',
+        whenToUse: `pick this for a full RAP stack on S/4 2020+ (10 objects, table → SRVB; not /abap-segw — that's ECC/older S/4 OData; not /abap-generate — that's one object)`,
         asks: 'the business object. e.g. "maintenance requests with draft and an approve action"',
     },
     {