@llm4ts/shell 2.27.0 → 2.28.0

package/kits/soap-ace/flows/lib/soap/Setup.js

@@ -0,0 +1,202 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { resolveProxy, resolveTls } from "./Auth.js";
+import { profilePath, readIfPresent, servicePaths } from "./Discover.js";
+import { renderDefaultStsTemplate, stsTemplatePath, templatePlaceholders } from "./Sts.js";
+import { displayUrl } from "./Transport.js";
+const proxyWords = (proxy) => proxy === undefined || proxy === "none"
+    ? "direct (no proxy)"
+    : `via ${proxy.url}${(proxy.noProxy ?? []).length === 0 ? "" : `, direct for ${proxy.noProxy?.join(", ")}`}${proxy.auth === undefined ? "" : ", with proxy credentials"}`;
+const tlsWords = (tls) => {
+    if (tls === undefined) {
+        return "system roots";
+    }
+    const parts = [];
+    parts.push(tls.trust === "ca-only"
+        ? "profile CA only"
+        : tls.ca === undefined && tls.caDir === undefined
+            ? "system roots"
+            : "system roots + profile CA");
+    if (tls.ca !== undefined)
+        parts.push(`ca ${tls.ca}`);
+    if (tls.caDir !== undefined)
+        parts.push(`caDir ${tls.caDir}`);
+    if (tls.pfx !== undefined)
+        parts.push("client pfx");
+    if (tls.cert !== undefined)
+        parts.push("client cert+key");
+    if (tls.servername !== undefined)
+        parts.push(`servername ${tls.servername}`);
+    return parts.join(", ");
+};
+const authWords = (side) => side?.auth === undefined || side.auth.scheme === "none"
+    ? "no auth"
+    : side.auth.scheme === "basic"
+        ? `basic as ${side.auth.user}`
+        : "bearer";
+/** The proxy variables of the environment, which the soap flows never read. */
+export const ignoredProxyVariables = (environment) => ["HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy"].filter((name) => (environment[name] ?? "").trim() !== "");
+/** `check`: the selected profile as the decisions it makes, line by line. No network. */
+export const checkReport = (options) => Effect.gen(function* () {
+    const path = profilePath(options.service, options.env);
+    const lines = [
+        `profile: ${path}${options.profile === undefined ? " (missing)" : ""}`
+    ];
+    const profile = options.profile;
+    if (profile === undefined) {
+        lines.push(`  write it with at least {"environment": "dev"}; see the soap-ace README`);
+    }
+    else {
+        lines.push(`environment: ${profile.environment}`);
+        lines.push(`call endpoint: ${profile.endpoint ?? "(from the WSDL)"}`);
+        for (const [name, side] of [
+            ["fetch", profile.fetch],
+            ["call", profile.call]
+        ]) {
+            lines.push(`${name}: ${authWords(side)}; ${proxyWords(side?.proxy)}; tls ${tlsWords(side?.tls)}`);
+        }
+        if (profile.wsSecurity !== undefined) {
+            lines.push(`ws-security: UsernameToken (${profile.wsSecurity.passwordType})`);
+        }
+        if (profile.sts === undefined) {
+            lines.push("sts: none");
+        }
+        else {
+            const template = stsTemplatePath(options.service, profile.sts);
+            const text = yield* readIfPresent(options.workspace, template);
+            lines.push(`sts: ${displayUrl(profile.sts.endpoint)}; ${proxyWords(profile.sts.proxy)}; tls ${tlsWords(profile.sts.tls)}; token element ${profile.sts.token?.element ?? "Assertion"}`);
+            lines.push(text === undefined
+                ? `  template ${template} missing: write it with soap-sample "sts init"`
+                : `  template ${template} fills ${templatePlaceholders(text).join(", ") || "(no placeholders)"}`);
+        }
+        const trust = yield* options.workspace.discover(`${servicePaths(options.service).trustDir}/*.pem`);
+        if (trust.length > 0) {
+            lines.push(`trusted chains: ${trust.map((file) => file.split("/").at(-1)).join(", ")}`);
+        }
+    }
+    const ignored = ignoredProxyVariables(options.environment);
+    if (ignored.length > 0) {
+        lines.push(`ignored: ${ignored.join(", ")} are set; the soap flows use only the profile's proxy`);
+    }
+    return lines;
+});
+// ---------------------------------------------------------------------------
+// trust
+export class TrustError extends Schema.TaggedError()("TrustError", {
+    side: Schema.String,
+    detail: Schema.String
+}) {
+    get message() {
+        return `trust ${this.side}: ${this.detail}`;
+    }
+}
+const endpointOf = (profile, side, fallback) => (side === "sts" ? profile.sts?.endpoint : (profile.endpoint ?? fallback));
+const sideConfig = (profile, side) => side === "sts"
+    ? {
+        ...(profile.sts?.tls === undefined ? {} : { tls: profile.sts.tls }),
+        ...(profile.sts?.proxy === undefined ? {} : { proxy: profile.sts.proxy })
+    }
+    : {
+        ...(profile[side]?.tls === undefined ? {} : { tls: profile[side]?.tls }),
+        ...(profile[side]?.proxy === undefined ? {} : { proxy: profile[side]?.proxy })
+    };
+export const describeChain = (chain) => [
+    `${chain.host}: ${chain.certificates.length} certificate(s)${chain.trustedBySystem ? ", trusted by the system roots" : `, NOT trusted by the system roots (${chain.authorizationError ?? "unknown issuer"})`}`,
+    ...chain.certificates.flatMap((certificate, index) => [
+        `  ${index + 1}. ${certificate.subject}`,
+        `     issuer: ${certificate.issuer}`,
+        `     valid: ${certificate.validFrom} → ${certificate.validTo}`,
+        `     sha256: ${certificate.fingerprint256}`
+    ])
+];
+const pemFileFor = (service, host) => `${servicePaths(service).trustDir}/${host.replace(/[^A-Za-z0-9.-]+/g, "_")}.pem`;
+/** Sets `<side>.tls.ca` in the selected profile's JSON text to the pinned file, keeping everything else. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const profileWithPinnedCa = (text, side, pemPath) => Effect.try({
+    try: () => {
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed)) {
+            throw new Error("not an object");
+        }
+        const sideValue = parsed[side];
+        const sideObject = isRecord(sideValue) ? sideValue : {};
+        const tlsValue = sideObject["tls"];
+        const tlsObject = isRecord(tlsValue) ? tlsValue : {};
+        const edited = {
+            ...parsed,
+            [side]: { ...sideObject, tls: { ...tlsObject, ca: `file:${pemPath}` } }
+        };
+        return `${JSON.stringify(edited, null, 2)}\n`;
+    },
+    catch: () => new TrustError({ side, detail: "the profile is not a JSON object; set tls.ca by hand" })
+});
+/** `trust <side>`: show the chain, pin it on a yes. */
+export const trustSide = (options) => Effect.gen(function* () {
+    const endpoint = endpointOf(options.profile, options.side, options.fallbackEndpoint);
+    if (endpoint === undefined) {
+        return yield* new TrustError({
+            side: options.side,
+            detail: options.side === "sts"
+                ? "the profile names no sts"
+                : "no endpoint in the profile or the WSDL"
+        });
+    }
+    const config = sideConfig(options.profile, options.side);
+    const proxy = yield* resolveProxy(options.secrets, config.proxy);
+    const tls = yield* resolveTls(options.secrets, config.tls);
+    const chain = yield* options.transport.peerChain(endpoint, {
+        ...(proxy === undefined ? {} : { proxy }),
+        ...(tls?.servername === undefined ? {} : { servername: tls.servername }),
+        timeout: Duration.seconds(20)
+    });
+    const lines = describeChain(chain);
+    if (chain.trustedBySystem) {
+        return { _tag: "AlreadyTrusted", lines };
+    }
+    if (chain.certificates.length === 0) {
+        return yield* new TrustError({
+            side: options.side,
+            detail: "the server presented no certificate"
+        });
+    }
+    const pemPath = pemFileFor(options.service, chain.host);
+    const existing = yield* readIfPresent(options.workspace, pemPath);
+    const shown = existing === undefined
+        ? lines
+        : [
+            ...lines,
+            `a chain for ${chain.host} is already pinned at ${pemPath}; this one replaces it`
+        ];
+    if (!(yield* options.confirm(shown))) {
+        return { _tag: "Declined", lines: shown };
+    }
+    yield* options.workspace.write(pemPath, chain.certificates.map((c) => c.pem).join(""));
+    const profileFile = profilePath(options.service, options.env);
+    const text = (yield* readIfPresent(options.workspace, profileFile)) ?? "{}";
+    yield* options.workspace.write(profileFile, yield* profileWithPinnedCa(text, options.side, pemPath));
+    return {
+        _tag: "Pinned",
+        lines: shown,
+        pem: pemPath,
+        profile: profileFile,
+        replaced: existing !== undefined
+    };
+});
+// ---------------------------------------------------------------------------
+// sts init
+/** `sts init`: the default template, unless one exists. */
+export const initStsTemplate = (workspace, service, profile) => Effect.gen(function* () {
+    if (profile.sts === undefined) {
+        return yield* new TrustError({
+            side: "sts",
+            detail: 'the profile names no "sts"; add it first'
+        });
+    }
+    const path = stsTemplatePath(service, profile.sts);
+    if ((yield* readIfPresent(workspace, path)) !== undefined) {
+        return { path, written: false };
+    }
+    yield* workspace.write(path, renderDefaultStsTemplate(profile.sts.soapVersion ?? "1.1"));
+    return { path, written: true };
+});

package/kits/soap-ace/flows/lib/soap/Sts.js

@@ -0,0 +1,216 @@
+import { randomBytes } from "node:crypto";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import { defaultStsTemplate, defaultTokenElement, resolvePrincipal, resolveProxy, resolveText, resolveTls } from "./Auth.js";
+import { envelopeNamespace, readEnvelope, soapHeaders, WsseNamespace, WsuNamespace } from "./Envelope.js";
+import { serviceDirectory } from "./Discover.js";
+import { displayUrl } from "./Transport.js";
+import { decodeXml, parseXml } from "./Xml.js";
+// A SAML bearer token from an STS (WS-Trust): the request is a template the
+// user owns under the service folder, filled with the credential, a nonce
+// and timestamps, posted with the STS side's auth, TLS and proxy; the first
+// element named `token.element` in the answer is carried as the raw bytes
+// of the response, so a signature over it survives. The token lives in
+// memory for the run only and is renewed before it expires.
+export class StsError extends Schema.TaggedError()("StsError", {
+    endpoint: Schema.String,
+    detail: Schema.String
+}) {
+    get message() {
+        return `STS ${this.endpoint}: ${this.detail}`;
+    }
+}
+export const stsTemplatePath = (service, config) => `${serviceDirectory(service)}/${config.template ?? defaultStsTemplate}`;
+const WsTrust = "http://docs.oasis-open.org/ws-sx/ws-trust/200512";
+const WsPolicy = "http://schemas.xmlsoap.org/ws/2004/09/policy";
+const WsAddressing = "http://www.w3.org/2005/08/addressing";
+const TokenProfile = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0";
+/** The WS-Trust 1.3 Issue request `sts init` writes; every placeholder is filled per call. */
+export const renderDefaultStsTemplate = (soapVersion = "1.1") => [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    "<!-- The STS request soap-sample fills before every token call. Placeholders:",
+    "     {{username}} {{password}} {{created}} {{expires}} {{nonce}} {{appliesTo}}.",
+    "     Edit freely: this file is yours; soap-sample only fills the placeholders. -->",
+    `<soapenv:Envelope xmlns:soapenv="${envelopeNamespace(soapVersion)}"`,
+    `    xmlns:wsse="${WsseNamespace}"`,
+    `    xmlns:wsu="${WsuNamespace}"`,
+    `    xmlns:wst="${WsTrust}"`,
+    `    xmlns:wsp="${WsPolicy}"`,
+    `    xmlns:wsa="${WsAddressing}">`,
+    "  <soapenv:Header>",
+    `    <wsa:Action>${WsTrust}/RST/Issue</wsa:Action>`,
+    '    <wsse:Security soapenv:mustUnderstand="1">',
+    '      <wsu:Timestamp wsu:Id="TS-1">',
+    "        <wsu:Created>{{created}}</wsu:Created>",
+    "        <wsu:Expires>{{expires}}</wsu:Expires>",
+    "      </wsu:Timestamp>",
+    '      <wsse:UsernameToken wsu:Id="UsernameToken-1">',
+    "        <wsse:Username>{{username}}</wsse:Username>",
+    `        <wsse:Password Type="${TokenProfile}#PasswordText">{{password}}</wsse:Password>`,
+    "        <wsse:Nonce>{{nonce}}</wsse:Nonce>",
+    "        <wsu:Created>{{created}}</wsu:Created>",
+    "      </wsse:UsernameToken>",
+    "    </wsse:Security>",
+    "  </soapenv:Header>",
+    "  <soapenv:Body>",
+    "    <wst:RequestSecurityToken>",
+    `      <wst:RequestType>${WsTrust}/Issue</wst:RequestType>`,
+    "      <wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>",
+    `      <wst:KeyType>${WsTrust}/Bearer</wst:KeyType>`,
+    "      <wsp:AppliesTo>",
+    "        <wsa:EndpointReference>",
+    "          <wsa:Address>{{appliesTo}}</wsa:Address>",
+    "        </wsa:EndpointReference>",
+    "      </wsp:AppliesTo>",
+    "    </wst:RequestSecurityToken>",
+    "  </soapenv:Body>",
+    "</soapenv:Envelope>",
+    ""
+].join("\n");
+const escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** Fills `{{name}}` placeholders; values are escaped for XML text. Unknown placeholders stay. */
+export const fillStsTemplate = (template, values) => {
+    const table = {
+        username: escapeXml(values.username),
+        password: escapeXml(Redacted.value(values.password)),
+        created: values.created,
+        expires: values.expires,
+        nonce: values.nonce,
+        appliesTo: escapeXml(values.appliesTo)
+    };
+    return Redacted.make(template.replace(/\{\{\s*([a-zA-Z]+)\s*\}\}/g, (whole, name) => table[name] ?? whole));
+};
+/** The names the template fills, for `check` to compare with what it holds. */
+export const templatePlaceholders = (template) => [...new Set([...template.matchAll(/\{\{\s*([a-zA-Z]+)\s*\}\}/g)].map((m) => m[1] ?? ""))].sort();
+const findElement = (root, local) => {
+    if (root.name.local === local) {
+        return root;
+    }
+    for (const child of root.children) {
+        if (child._tag === "element") {
+            const found = findElement(child, local);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+    }
+    return undefined;
+};
+/**
+ * The first element named `local` in `text`, exactly as written (its span),
+ * or `undefined`. The text must be the parsed document: spans index it.
+ */
+export const extractElementRaw = (text, root, local) => {
+    const found = findElement(root, local);
+    return found?.span === undefined ? undefined : text.slice(found.span.start, found.span.end);
+};
+const attributeOf = (element, local) => element.attributes.find((attribute) => attribute.name.local === local)?.value;
+/** `Conditions/@NotOnOrAfter` of a SAML assertion, when it carries one. */
+export const notOnOrAfterOf = (root, tokenLocal) => {
+    const assertion = findElement(root, tokenLocal);
+    if (assertion === undefined) {
+        return undefined;
+    }
+    const conditions = findElement(assertion, "Conditions");
+    const value = conditions === undefined ? undefined : attributeOf(conditions, "NotOnOrAfter");
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+};
+/** One STS call: fill the template, post it, carry the token element verbatim. */
+export const fetchSamlToken = (options) => Effect.gen(function* () {
+    const { config } = options;
+    const shown = displayUrl(config.endpoint);
+    const path = stsTemplatePath(options.service, config);
+    const found = yield* options.workspace.discover(path);
+    if (!found.includes(path)) {
+        return yield* new StsError({
+            endpoint: shown,
+            detail: `no request template at ${path}; write it with soap-sample "sts init"`
+        });
+    }
+    const template = yield* options.workspace.read(path);
+    const now = options.now ?? (() => new Date());
+    const random = options.random ?? ((size) => new Uint8Array(randomBytes(size)));
+    const created = now();
+    const envelope = fillStsTemplate(template, {
+        username: yield* resolvePrincipal(options.secrets, config.auth.user),
+        password: yield* resolveText(options.secrets, config.auth.password),
+        created: created.toISOString(),
+        expires: new Date(created.getTime() + 5 * 60_000).toISOString(),
+        nonce: Buffer.from(random(16)).toString("base64"),
+        appliesTo: config.appliesTo ?? ""
+    });
+    const tls = yield* resolveTls(options.secrets, config.tls);
+    const proxy = yield* resolveProxy(options.secrets, config.proxy);
+    const version = config.soapVersion ?? "1.1";
+    const response = yield* options.transport.send({
+        method: "POST",
+        url: config.endpoint,
+        headers: soapHeaders(version, `${WsTrust}/RST/Issue`),
+        secretHeaders: [],
+        body: envelope,
+        ...(tls === undefined ? {} : { tls }),
+        ...(proxy === undefined ? {} : { proxy }),
+        timeout: Duration.seconds(config.timeoutSeconds ?? 60)
+    });
+    const text = yield* decodeXml(response.body, "sts response");
+    const root = yield* parseXml(text, { source: "sts response" }).pipe(Effect.mapError(() => new StsError({
+        endpoint: shown,
+        detail: `HTTP ${response.status} with a body that is not XML`
+    })));
+    const read = yield* readEnvelope(root).pipe(Effect.option);
+    if (read._tag === "Some" && read.value.fault !== undefined) {
+        return yield* new StsError({
+            endpoint: shown,
+            detail: `fault ${read.value.fault.code}: ${read.value.fault.reason}`
+        });
+    }
+    if (response.status < 200 || response.status >= 300) {
+        return yield* new StsError({ endpoint: shown, detail: `HTTP ${response.status}` });
+    }
+    const element = config.token?.element ?? defaultTokenElement;
+    const raw = extractElementRaw(text, root, element);
+    if (raw === undefined) {
+        return yield* new StsError({
+            endpoint: shown,
+            detail: `no ${element} element in the response (set sts.token.element to the one it carries)`
+        });
+    }
+    return {
+        token: Redacted.make(raw),
+        notOnOrAfter: notOnOrAfterOf(root, element),
+        element,
+        chars: raw.length
+    };
+});
+/**
+ * The run's token: fetched on first use, renewed `renewBeforeSeconds`
+ * before `NotOnOrAfter` (a token without one lasts the run). Never persisted.
+ */
+export const makeTokenSource = (options) => Effect.gen(function* () {
+    const cache = yield* Ref.make(undefined);
+    const count = yield* Ref.make(0);
+    const now = options.now ?? (() => new Date());
+    const margin = (options.config.renewBeforeSeconds ?? 60) * 1000;
+    const fresh = (token) => token !== undefined &&
+        (token.notOnOrAfter === undefined || token.notOnOrAfter.getTime() - margin > now().getTime());
+    return {
+        current: Effect.gen(function* () {
+            const cached = yield* Ref.get(cache);
+            if (fresh(cached)) {
+                return cached;
+            }
+            const token = yield* fetchSamlToken(options);
+            yield* Ref.set(cache, token);
+            yield* Ref.update(count, (n) => n + 1);
+            return token;
+        }),
+        fetches: Ref.get(count)
+    };
+});

package/kits/soap-ace/flows/lib/soap/Stub.js

@@ -30,5 +30,12 @@ export const makeDirectoryStubTransport = (directory, catalog) => ({
             body: new Uint8Array(bytes),
             elapsedMs: 1
         })), Effect.orElseSucceed(() => stubFault(`stub: no ${operation.name}.xml`)));
-    }
+    },
+    // A stub answers from files: no server, so no chain to show.
+    peerChain: (url) => Effect.succeed({
+        host: new URL(url).hostname,
+        certificates: [],
+        trustedBySystem: true,
+        authorizationError: undefined
+    })
 });