@llm4ts/shell 2.26.0 → 2.28.0

package/flows/epic-retro.js

@@ -0,0 +1,66 @@
+// Read what a failed epic-stories run left behind and propose the fixes the next run applies once approved.
+//
+//   llm4ts run epic-retro --repo ~/demo/portal                       # the one open epic, its latest run
+//   llm4ts run epic-retro --repo ~/demo/portal -- --epic <id>        # one epic
+//   llm4ts run epic-retro --repo ~/demo/portal -- --epic <id> --run run-1759…   # one run of it
+//
+// The evidence is the run's trace, its transcripts when it was started with
+// --transcript, the board, the report, and each story's plan, findings and
+// judge verdict under .llm4ts/epics/<epic-id>/. Code digests them (the digest
+// is written first, at retro/<runId>.digest.md); one read-only seat
+// (LLM4TS_REASONER, the judge seat) turns the digest into a proposal: per
+// story a diagnosis and exactly one fix — tasks appended to its plan, an
+// edit to its entry (which restarts it), a refine round, or nothing — plus
+// run advice and, where the library misbehaved, advice for llm4ts
+// (retro/<runId>-library.md). Code validates the proposal before writing
+// retro/<runId>.md, which ends in `- [ ] Approved`. Tick it and rerun
+// epic-stories: the approved fixes are applied before any story runs, and
+// the report is marked Applied. Nothing is applied unapproved; nothing in
+// the target's git is touched.
+import { join } from "node:path";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import { ScriptUsage, asReadOnly, nodePlainFileStore, resolveFlowInput, runFlowMain, runNode } from "@llm4ts/runner";
+import { loadTranscript, nodeTranscriptFiles } from "@llm4ts/runner/Transcripts";
+import { parseEpicRetroArgs, resolveRetroTarget, runRetro } from "./lib/epic-retro.js";
+import { chooseEpic, defaultEpic, epicsDir, listEpics, reasonerFromEnvironment } from "./lib/epic-stories.js";
+const program = Effect.gen(function* () {
+    const flags = yield* parseEpicRetroArgs(process.argv.slice(2));
+    const given = yield* resolveFlowInput("", flags.rest);
+    const files = nodePlainFileStore;
+    const epics = yield* listEpics(files, given.workDir);
+    const choice = yield* chooseEpic({ text: "", epic: flags.epic, epics, defaultEpic });
+    if (choice._tag !== "Existing") {
+        return yield* ScriptUsage.make({
+            message: `no planned epic to look at in ${given.workDir}; run epic-stories first`
+        });
+    }
+    const epicDir = choice.epic.dir;
+    const stateDir = join(epicsDir(given.workDir), epicDir);
+    const target = yield* resolveRetroTarget(files, stateDir, flags.run);
+    const transcriptDir = join(given.workDir, ".llm4ts", "transcripts", target.run.runId);
+    const reasoning = asReadOnly(yield* reasonerFromEnvironment(process.env));
+    const outcome = yield* runNode({
+        workDir: given.workDir,
+        workspace: given.workspace,
+        userPrompt: `retro of run ${target.run.runId} of epic ${target.plan.epicId}`,
+        // No coder turn is ever taken: the read-only reasoning seat fills both.
+        coder: reasoning,
+        reasoning,
+        environment: process.env
+    }, (context) => runRetro({
+        files,
+        events: context.events,
+        seat: context.judge ?? context.reasoning,
+        workDir: given.workDir,
+        epicDir,
+        target,
+        transcript: (lane) => loadTranscript(nodeTranscriptFiles, transcriptDir, { lane }),
+        environment: process.env,
+        now: Date.now()
+    }));
+    if (outcome._tag === "NothingToDo") {
+        yield* Console.log(outcome.message);
+    }
+});
+runFlowMain(program);

package/flows/lib/epic-retro.js

@@ -0,0 +1,150 @@
+/**
+ * epic-retro: read what a failed epic-stories run left behind, explain each
+ * failed story, and propose the fix the next run applies once approved.
+ * The policy (digest, proposal schema, validation, report, apply) lives in
+ * `@llm4ts/flow/Retro`; this module finds the run and its files and drives
+ * one read-only seat.
+ */
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import { readEpicRuns } from "@llm4ts/flow/EpicRuns";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { readTrace } from "@llm4ts/flow/Replay";
+import { RetroProposal, defaultRetroChars, loadEpicFiles, loadStoryFiles, renderRetroDigest, retroCandidates, retroPaths, retroPrompt, retroProposalJsonSchema, validateRetroProposal, writeRetro } from "@llm4ts/flow/Retro";
+import { makeStoryPlanStore } from "@llm4ts/flow/StoryPlan";
+import { structuredAndPublish } from "@llm4ts/flow/Usage";
+import { ScriptUsage } from "@llm4ts/runner/FlowArgs";
+import { roundDir } from "./epic-stories.js";
+export const epicRetroUsage = [
+    "usage: llm4ts run epic-retro --repo <target> [-- --epic <id>] [-- --run <runId>]",
+    "  --epic <id>   the epic (folder name or plan id); default: the one open epic",
+    "  --run <id>    the run to look at; default: the epic's latest run",
+    "Reads the run's trace, transcripts (when kept), board, report, story plans, findings and",
+    "verdicts; writes .llm4ts/epics/<epic>/retro/<runId>.md with proposed fixes behind an",
+    "approval line, and <runId>-library.md with advice for llm4ts when there is any."
+].join("\n");
+export const parseEpicRetroArgs = (argv) => Effect.gen(function* () {
+    let epic;
+    let run;
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? "";
+        const valued = (name) => {
+            const value = argument.includes("=") ? argument.slice(name.length + 1) : argv[index + 1];
+            if (!argument.includes("=")) {
+                index += 1;
+            }
+            return value === undefined || value.trim().length === 0 || value.startsWith("--")
+                ? ScriptUsage.make({ message: `${name} needs a value\n${epicRetroUsage}` })
+                : Effect.succeed(value.trim());
+        };
+        if (argument === "--epic" || argument.startsWith("--epic=")) {
+            epic = yield* valued("--epic");
+        }
+        else if (argument === "--run" || argument.startsWith("--run=")) {
+            run = yield* valued("--run");
+        }
+        else {
+            rest.push(argument);
+        }
+    }
+    return { epic, run, rest };
+});
+export const resolveRetroTarget = Effect.fn("epic-retro.resolveTarget")(function* (files, epicStateDir, runId) {
+    const runs = yield* readEpicRuns(files, epicStateDir);
+    const run = runId === undefined ? runs.at(-1) : runs.find((candidate) => candidate.runId === runId);
+    if (run === undefined) {
+        return yield* ScriptUsage.make({
+            message: runId === undefined
+                ? `no run recorded in ${join(epicStateDir, "runs.jsonl")}; run epic-stories first`
+                : `no run '${runId}' in ${join(epicStateDir, "runs.jsonl")}; recorded: ${runs.map((r) => r.runId).join(", ") || "none"}`
+        });
+    }
+    const stateDir = run.round !== undefined && (run.action === "RunRound" || run.action === "PlanRound")
+        ? roundDir(epicStateDir, run.round)
+        : epicStateDir;
+    const plan = yield* makeStoryPlanStore(files).load(join(stateDir, "plan.md"));
+    if (plan === undefined) {
+        return yield* ScriptUsage.make({ message: `no plan at ${join(stateDir, "plan.md")}` });
+    }
+    return { run, stateDir, plan };
+});
+const retroChars = (environment) => {
+    const value = Number.parseInt(environment.LLM4TS_RETRO_CHARS ?? "", 10);
+    return Number.isInteger(value) && value > 0 ? value : defaultRetroChars;
+};
+/** The whole retro: evidence, one structured call, validation, the files. */
+export const runRetro = Effect.fn("epic-retro.run")(function* (deps) {
+    const { files, target } = deps;
+    const { stateDir, plan, run } = target;
+    const trace = yield* readTrace(files, run.tracePath);
+    const epic = yield* loadEpicFiles(files, stateDir);
+    const stories = yield* Effect.forEach(plan.stories, (story) => loadStoryFiles(files, stateDir, story));
+    const withoutTranscripts = {
+        runId: run.runId,
+        plan,
+        trace,
+        transcripts: undefined,
+        report: epic.report,
+        board: epic.board,
+        stories,
+        budget: retroChars(deps.environment)
+    };
+    const candidates = retroCandidates(withoutTranscripts);
+    if (candidates.length === 0) {
+        return {
+            _tag: "NothingToDo",
+            message: `run ${run.runId} of epic ${plan.epicId} left no failed, waiting or unfinished story; nothing to look at`
+        };
+    }
+    // Transcripts are read per candidate lane; the first answer says whether
+    // the run kept any at all.
+    const transcripts = new Map();
+    let kept = false;
+    for (const candidate of candidates) {
+        const entries = yield* deps.transcript(candidate.story.id);
+        if (entries !== undefined) {
+            kept = true;
+            transcripts.set(candidate.story.id, entries);
+        }
+    }
+    const inputs = { ...withoutTranscripts, transcripts: kept ? transcripts : undefined };
+    const digest = renderRetroDigest(inputs);
+    const paths = retroPaths(stateDir, run.runId);
+    // The digest is on disk before the seat is asked: a failed call still leaves it to read.
+    yield* files.writeAtomic(paths.digest, digest);
+    yield* deps.events.publish(Info.make({
+        message: `retro: ${candidates.length} stor${candidates.length === 1 ? "y" : "ies"} to look at in run ${run.runId}${kept ? "" : " (no transcripts; rerun with --transcript for more)"} — digest at ${paths.digest}`
+    }));
+    const withPlans = new Set(stories.filter((entry) => entry.plan !== undefined).map((entry) => entry.story.id));
+    const proposal = yield* structuredAndPublish(deps.seat, deps.events, retroPrompt(digest, [...withPlans]), RetroProposal, retroProposalJsonSchema, "retro");
+    const validated = validateRetroProposal(proposal, plan, withPlans);
+    const written = yield* writeRetro(files, stateDir, {
+        runId: run.runId,
+        plan,
+        validated,
+        workDir: deps.workDir,
+        epicDir: deps.epicDir,
+        digest,
+        at: deps.now
+    });
+    const applies = validated.proposal.stories.filter((s) => s.kind === "tasks" || s.kind === "story");
+    const summary = [
+        `retro of run ${run.runId}: ${validated.proposal.summary.trim()}`,
+        ...validated.proposal.stories.map((entry) => `  ${entry.id}: ${entry.kind === "tasks" ? `${entry.tasks?.length ?? 0} task(s)` : entry.kind === "story" ? "edit the story (restart)" : entry.kind === "refine" ? "needs a refine round" : "no change"}`),
+        ...(validated.dropped.length === 0
+            ? []
+            : [`  dropped ${validated.dropped.length} item(s) the plan cannot take; see the report`]),
+        `report: ${written.report}`,
+        ...(validated.proposal.libraryAdvice.length === 0
+            ? []
+            : [`advice for llm4ts: ${written.library}`]),
+        applies.length === 0
+            ? "nothing to apply; the report is for reading"
+            : `tick '- [x] Approved' in the report, then rerun: llm4ts run epic-stories --repo ${deps.workDir} -- --epic ${deps.epicDir}`
+    ];
+    for (const line of summary) {
+        yield* deps.events.publish(Info.make({ message: line }));
+    }
+    return { _tag: "Written", paths: written, summary };
+});

package/flows/lib/epic-stories.js

@@ -16,6 +16,7 @@ import { structuredAndPublish } from "@llm4ts/flow/Flow";
 import { EpicBriefInvalid, EpicBriefNotApproved, EpicCheckoutDirty, LandingFailed, RefineRefused } from "@llm4ts/flow/FlowError";
 import { Info } from "@llm4ts/flow/FlowEvents";
 import { nodePreflight } from "@llm4ts/flow/NodePreflight";
+import { applyApprovedRetros } from "@llm4ts/flow/Retro";
 import { statusPaths } from "@llm4ts/flow/GitTool";
 import { EpicLanded, EpicLandedVersion, landedPath } from "@llm4ts/flow/Landing";
 import { RefineProposal, assembleRound, countNotPlanned, earlierStories, refineProposalJsonSchema, renderNotPlanned, roundPrefix, roundRepair, runAction } from "@llm4ts/flow/RefineRound";
@@ -1050,7 +1051,7 @@ const withOptionalModel = (config, model) => {
 const withExtraFlags = (config, flags) => Object.keys(flags).length === 0
     ? config
     : CliConnectorConfig.make({ ...config, flags: { ...config.flags, ...flags } });
-const defaultEpic = "Add the retail customer's current account (Conto) with balance and movements, and wire " +
+export const defaultEpic = "Add the retail customer's current account (Conto) with balance and movements, and wire " +
     "transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.";
 export const runEpicStories = (options) => Effect.gen(function* () {
     const flags = yield* parseEpicArgs(process.argv.slice(2));
@@ -1167,14 +1168,31 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             return;
         }
         const epicBranch = `epic/${plan.epicId}`;
+        // An approved retro of an earlier run (epic-retro) is applied before
+        // any story runs: tasks onto story plans, story edits onto the plan.
+        const retroState = action._tag === "RunRound"
+            ? (rounds.find((round) => round.round === action.round)?.stateDir ?? stateDir)
+            : stateDir;
+        const retroPlan = action._tag === "RunRound"
+            ? rounds.find((round) => round.round === action.round)?.plan
+            : action._tag === "RunPlan"
+                ? plan
+                : undefined;
+        const applied = retroPlan === undefined
+            ? undefined
+            : yield* applyApprovedRetros(files, retroState, retroPlan, events, Date.now());
         // The unit the executor works on: the epic's plan, or one refine round.
         // Same branch, seats, gates and judge; its own plan and state folder.
-        let unit = { plan, stateDir, label: `Epic: ${plan.epicId}` };
+        let unit = {
+            plan: action._tag === "RunPlan" && applied !== undefined ? applied.plan : plan,
+            stateDir,
+            label: `Epic: ${plan.epicId}`
+        };
         if (action._tag === "RunRound") {
             const open = rounds.find((round) => round.round === action.round);
             if (open?.plan !== undefined) {
                 unit = {
-                    plan: open.plan,
+                    plan: applied?.plan ?? open.plan,
                     stateDir: open.stateDir,
                     label: `Epic: ${plan.epicId} · round ${open.round}`
                 };
@@ -1354,5 +1372,25 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         yield* events.publish(Info.make({
             message: `${unit.label.replace("Epic: ", "epic ")}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("waiting")} waiting — report at ${join(unit.stateDir, "report.md")} (usage figures estimated)`
         }));
+        const hint = retroHint(report, input.workDir, epicId);
+        if (hint !== undefined) {
+            yield* events.publish(Info.make({ message: hint }));
+        }
     }));
 });
+/**
+ * The one command away from a red run: what to type to have the run's trace
+ * and transcripts read and fixes proposed. `undefined` when every story is done.
+ */
+export const retroHint = (report, workDir, epicDir) => {
+    const failed = report.count("failed");
+    const waiting = report.count("waiting");
+    if (failed === 0 && waiting === 0) {
+        return undefined;
+    }
+    const what = [
+        ...(failed === 0 ? [] : [`${failed} failed`]),
+        ...(waiting === 0 ? [] : [`${waiting} waiting`])
+    ].join(", ");
+    return `${what}: llm4ts run epic-retro --repo ${workDir} -- --epic ${epicDir} reads this run's trace and transcripts and proposes fixes for the next run`;
+};

package/kits/soap-ace/README.md

@@ -116,6 +116,10 @@ llm4ts run soap-sample --repo . "propose cercaMovimenti"                 # scena
 llm4ts run soap-sample --repo . "call cercaMovimenti"                    # every request of the operation
 llm4ts run soap-sample --repo . -- --allow-mutating revocaBonifico "call revocaBonifico/gia-eseguito"
 llm4ts run soap-sample --repo . list
+llm4ts run soap-sample --repo . "check"                                  # the selected profile as decisions, no network
+llm4ts run soap-sample --repo . "trust call"                             # capture and pin the chain the endpoint presents
+llm4ts run soap-sample --repo . "sts init"                               # write the STS request template
+llm4ts run soap-sample --repo . -- --env uat "call all"                  # with auth.uat.json (or LLM4TS_SOAP_ENV=uat)
 ```
 
 A request is a YAML projection of the XSD, one file per scenario under
@@ -312,6 +316,70 @@ read, and errors name the reference, never its value.
 Persisted exchanges drop `wsse:Security` headers and credential-bearing HTTP
 headers (`authorization`, cookies, anything named like a token or secret).
 
+## Environments, proxies, trust and STS tokens
+
+Locked-down environments differ in where the proxy is, whose CA signed the
+ESB, and which STS issues the token (ADR 0024). One file per environment
+holds all of it: `auth.<env>.json` beside `auth.json`, selected by
+`LLM4TS_SOAP_ENV=uat` or `-- --env uat`; a named environment without a
+file is an error. Every flow prints the file it loaded.
+
+```json
+{
+  "environment": "uat",
+  "endpoint": "https://esb-uat.bank.internal/soap/DemoBank",
+  "call": {
+    "proxy": "none",
+    "tls": { "ca": "file:.llm4ts/soap/DemoBank/trust/esb-uat.bank.internal.pem" }
+  },
+  "fetch": {
+    "proxy": { "url": "http://proxy.bank.internal:3128", "noProxy": ["*.bank.internal"] }
+  },
+  "sts": {
+    "endpoint": "https://sts-uat.bank.internal/trust/13/usernamemixed",
+    "auth": { "user": "env:STS_USER", "password": "env:STS_PASSWORD" },
+    "appliesTo": "https://esb-uat.bank.internal/soap/DemoBank",
+    "token": { "element": "Assertion" },
+    "renewBeforeSeconds": 60,
+    "timestamp": true
+  }
+}
+```
+
+- **Proxies** are explicit per side (`fetch`, `call`, `sts`): `{ "url",
+"noProxy": ["host", "*.suffix"], "auth": {basic, references} }` or
+  `"none"` (the default). The transport opens an HTTP CONNECT tunnel; the
+  proxy environment variables are never read, and `check` lists them as
+  set-and-ignored. A refused tunnel is a `proxy` transport error.
+- **CA material** adds to Node's system roots: `tls.ca` (a PEM file) and
+  `tls.caDir` (a directory of `.pem`/`.crt`). `tls.trust: "ca-only"` trusts
+  only the profile's. `tls.servername` names the host behind a front door.
+  Verification is never switched off.
+- **`trust call|fetch|sts`** connects to that side's endpoint without
+  verifying, sends nothing, prints every certificate of the chain (subject,
+  issuer, validity, SHA-256 fingerprint) and whether the system already
+  trusts it, asks `trust this chain? [y/N]` (`-- --yes` headless), and on
+  yes writes `trust/<host>.pem` (gitignored) and sets that side's `tls.ca`
+  in the selected profile. A changed certificate is shown as a replacement
+  and asked again. A `tls` error that says "capture it with trust" is this
+  case.
+- **STS**: with an `sts` section every `call` first obtains a SAML bearer
+  token. `sts init` writes `sts.request.xml`, a WS-Trust 1.3 Issue envelope
+  with `{{username}}`, `{{password}}`, `{{created}}`, `{{expires}}`,
+  `{{nonce}}`, `{{appliesTo}}`; edit it when the STS differs, the kit only
+  fills the placeholders. The first element named `token.element` (default
+  `Assertion`, any namespace) is taken from the response as its raw bytes,
+  so a signed assertion survives, and sent inside `wsse:Security` after the
+  `wsu:Timestamp` (`timestamp: true`) and the UsernameToken when
+  `wsSecurity` is also set. The token lives in memory for the run and is
+  renewed `renewBeforeSeconds` before its `NotOnOrAfter`; it is never
+  written anywhere. `StsError` names the fault, the status or the element
+  it looked for.
+- **`check`** prints the selected file, each side's endpoint, proxy decision
+  and CA sources, the STS and its template's placeholders, the pinned
+  chains, and the ignored proxy variables. It makes no connection: run it
+  first, then `trust`, then `sts init`, then `call`.
+
 ## Masking
 
 Every SOAP sample is masked before it is written anywhere or shown to a

package/kits/soap-ace/fixtures/demo-bank-soap/RUNBOOK.md

@@ -59,6 +59,21 @@ and set `LLM4TS_SOAP_SERVICE`.
 }
 ```
 
+Per environment, `auth.test.json` / `auth.uat.json` next to it, picked by
+`LLM4TS_SOAP_ENV` or `-- --env`. In a locked-down network run, in order:
+
+```bash
+llm4ts run soap-sample --repo . "check"          # the profile as decisions, no network
+llm4ts run soap-sample --repo . "trust call"     # pin the ESB's chain after reading its fingerprint
+llm4ts run soap-sample --repo . "trust sts"      # and the STS's, when the profile names one
+llm4ts run soap-sample --repo . "sts init"       # the WS-Trust template; edit it if the STS differs
+```
+
+Proxies are explicit per side in the profile (`proxy`), never read from
+the environment; CA PEMs add to the system roots; the SAML token the STS
+issues is carried byte for byte and never persisted (README, "Environments,
+proxies, trust and STS tokens").
+
 ## 3. Samples
 
 ```bash

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

@@ -1,4 +1,5 @@
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
@@ -31,20 +32,75 @@ export class NoAuth extends Schema.Class("NoAuth")({
 }) {
 }
 export const HttpAuth = Schema.Union([NoAuth, BasicAuth, BearerAuth]);
-/** Client TLS: PEM cert+key, or a PKCS#12 bundle; an optional CA bundle. */
+/** How the profile's CA material combines with Node's system roots. */
+export const TlsTrust = Schema.Literals(["system+ca", "ca-only"]);
+/**
+ * Client TLS: PEM cert+key, or a PKCS#12 bundle; CA material as a PEM file
+ * (`ca`) and/or a directory of PEMs (`caDir`), added to the system roots
+ * unless `trust` is `ca-only`; `servername` for a host behind a front door.
+ */
 export class TlsConfig extends Schema.Class("TlsConfig")({
     cert: Schema.optionalKey(SecretRef),
     key: Schema.optionalKey(SecretRef),
     pfx: Schema.optionalKey(SecretRef),
     passphrase: Schema.optionalKey(SecretRef),
-    ca: Schema.optionalKey(SecretRef)
+    ca: Schema.optionalKey(SecretRef),
+    caDir: Schema.optionalKey(Schema.String),
+    trust: Schema.optionalKey(TlsTrust),
+    servername: Schema.optionalKey(Schema.String)
 }) {
 }
+const ProxyUrl = Schema.String.check(Schema.isPattern(/^https?:\/\/[^/?#@]+\/?$/i, {
+    message: "an http(s) proxy origin without credentials or path; credentials go in auth"
+}));
+/**
+ * An explicit HTTP CONNECT proxy for one side, with the hosts that bypass
+ * it (`*.suffix` wildcards). Environment proxy variables are never read.
+ */
+export class ProxyConfig extends Schema.Class("ProxyConfig")({
+    url: ProxyUrl,
+    noProxy: Schema.optionalKey(Schema.Array(Schema.String)),
+    auth: Schema.optionalKey(BasicAuth)
+}) {
+}
+export const ProxySetting = Schema.Union([Schema.Literal("none"), ProxyConfig]);
 export class HttpSide extends Schema.Class("HttpSide")({
     auth: Schema.optionalKey(HttpAuth),
-    tls: Schema.optionalKey(TlsConfig)
+    tls: Schema.optionalKey(TlsConfig),
+    proxy: Schema.optionalKey(ProxySetting)
+}) {
+}
+/** The credential the STS request template is filled with. */
+export class StsCredential extends Schema.Class("StsCredential")({
+    user: Principal,
+    password: SecretRef
+}) {
+}
+/**
+ * A SAML bearer token from an STS: the template under the service folder
+ * is filled and posted to `endpoint` with this side's auth, TLS and proxy;
+ * the first element named `token.element` in the answer is carried, bytes
+ * unchanged, in every call's WS-Security header.
+ */
+export class StsConfig extends Schema.Class("StsConfig")({
+    endpoint: Schema.String.check(Schema.isPattern(/^https?:\/\/[^/?#@]+(?:[/?#][^@]*)?$/i, {
+        message: "an http(s) URL without credentials; secrets go in references"
+    })),
+    soapVersion: Schema.optionalKey(Schema.Literals(["1.1", "1.2"])),
+    /** Relative to the service folder; `sts init` writes the default. */
+    template: Schema.optionalKey(Schema.String),
+    auth: StsCredential,
+    appliesTo: Schema.optionalKey(Schema.String),
+    token: Schema.optionalKey(Schema.Struct({ element: Schema.optionalKey(Schema.String) })),
+    renewBeforeSeconds: Schema.optionalKey(Schema.Int),
+    timestamp: Schema.optionalKey(Schema.Boolean),
+    tls: Schema.optionalKey(TlsConfig),
+    proxy: Schema.optionalKey(ProxySetting),
+    timeoutSeconds: Schema.optionalKey(Schema.Int)
 }) {
 }
+export const defaultStsTemplate = "sts.request.xml";
+export const defaultTokenElement = "Assertion";
 export class UsernameToken extends Schema.Class("UsernameToken")({
     user: Principal,
     password: SecretRef,
@@ -69,10 +125,14 @@ export class AuthProfile extends Schema.Class("AuthProfile")({
     /** Calling operations. */
     call: Schema.optionalKey(HttpSide),
     wsSecurity: Schema.optionalKey(UsernameToken),
+    /** A SAML bearer token from an STS, carried by every call. */
+    sts: Schema.optionalKey(StsConfig),
     mutating: Schema.optionalKey(MutatingPolicies),
     timeoutSeconds: Schema.optionalKey(Schema.Int)
 }) {
 }
+/** `auth.json`, or `auth.<env>.json` when an environment is selected. */
+export const profileFileName = (env) => env === undefined || env.trim() === "" ? "auth.json" : `auth.${env.trim()}.json`;
 export const defaultMutatingPolicy = (environment) => environment === "dev" ? "confirm" : "flag";
 export const mutatingPolicy = (profile) => profile.mutating?.[profile.environment] ?? defaultMutatingPolicy(profile.environment);
 export class AuthProfileError extends Schema.TaggedError()("AuthProfileError", {
@@ -84,11 +144,11 @@ export class AuthProfileError extends Schema.TaggedError()("AuthProfileError", {
         return `auth profile: ${this.subject}: ${this.detail}`;
     }
 }
-export const decodeAuthProfile = (text) => Schema.decodeUnknownEffect(Schema.fromJsonString(AuthProfile))(text).pipe(Effect.mapError((error) => 
+export const decodeAuthProfile = (text, file = "auth.json") => Schema.decodeUnknownEffect(Schema.fromJsonString(AuthProfile))(text).pipe(Effect.mapError((error) => 
 // Schema issues quote the offending input; a mistyped secret could be
 // in it, so only the paths of the issue are kept.
 new AuthProfileError({
-    subject: "auth.json",
+    subject: file,
     detail: `invalid profile (${issuePaths(error.message)})`
 })));
 /** Keep only the `at ["a"]["b"]` locations of a schema message, dropping any quoted value. */
@@ -137,27 +197,81 @@ export const resolveTls = (source, tls) => tls === undefined
         const cert = yield* optionalSecret(source, "cert", tls.cert);
         const key = yield* optionalSecret(source, "key", tls.key);
         const pfx = yield* optionalSecret(source, "pfx", tls.pfx);
-        const ca = yield* optionalSecret(source, "ca", tls.ca);
+        const caFile = tls.ca === undefined ? undefined : Redacted.value(yield* resolveSecret(source, tls.ca));
+        let caDir;
+        if (tls.caDir !== undefined) {
+            if (source.readPemDirectory === undefined) {
+                return yield* new AuthProfileError({
+                    subject: "tls.caDir",
+                    detail: "this source cannot read a directory"
+                });
+            }
+            caDir = yield* source.readPemDirectory(tls.caDir);
+        }
+        const ca = caFile === undefined && caDir === undefined
+            ? {}
+            : { ca: Redacted.make(concatPem(caFile, caDir)) };
         const passphrase = tls.passphrase === undefined
             ? {}
             : { passphrase: yield* resolveText(source, tls.passphrase) };
-        return { ...cert, ...key, ...pfx, ...ca, ...passphrase };
+        return {
+            ...cert,
+            ...key,
+            ...pfx,
+            ...ca,
+            ...passphrase,
+            ...(tls.trust === undefined ? {} : { trust: tls.trust }),
+            ...(tls.servername === undefined ? {} : { servername: tls.servername })
+        };
+    });
+const concatPem = (...parts) => {
+    const present = parts.filter((part) => part !== undefined);
+    const joined = present.map((part) => new TextDecoder().decode(part).trimEnd()).join("\n");
+    return new TextEncoder().encode(`${joined}\n`);
+};
+/** Whether a host bypasses the proxy: exact match, or `*.suffix` / `.suffix`. */
+export const bypassesProxy = (host, noProxy) => {
+    const lower = host.toLowerCase();
+    return noProxy.some((entry) => {
+        const pattern = entry.trim().toLowerCase();
+        if (pattern === "")
+            return false;
+        if (pattern === "*")
+            return true;
+        if (pattern.startsWith("*.") || pattern.startsWith(".")) {
+            const suffix = pattern.replace(/^\*/, "");
+            return lower.endsWith(suffix) && lower.length > suffix.length;
+        }
+        return lower === pattern;
+    });
+};
+export const resolveProxy = (source, proxy) => proxy === undefined || proxy === "none"
+    ? Effect.succeed(undefined)
+    : Effect.gen(function* () {
+        const authorization = proxy.auth === undefined
+            ? {}
+            : {
+                authorization: basicHeader(yield* resolvePrincipal(source, proxy.auth.user), yield* resolveText(source, proxy.auth.password))
+            };
+        return { url: proxy.url, noProxy: proxy.noProxy ?? [], ...authorization };
     });
 const basicHeader = (user, password) => Redacted.make(`Basic ${Buffer.from(`${user}:${Redacted.value(password)}`, "utf8").toString("base64")}`);
 export const resolveSide = (source, side) => Effect.gen(function* () {
     const auth = side?.auth;
     const tls = yield* resolveTls(source, side?.tls);
+    const proxy = yield* resolveProxy(source, side?.proxy);
     if (auth === undefined || auth.scheme === "none")
-        return { headers: [], tls };
+        return { headers: [], tls, proxy };
     if (auth.scheme === "basic") {
         const user = yield* resolvePrincipal(source, auth.user);
         const password = yield* resolveText(source, auth.password);
-        return { headers: [["authorization", basicHeader(user, password)]], tls };
+        return { headers: [["authorization", basicHeader(user, password)]], tls, proxy };
     }
     const token = yield* resolveText(source, auth.token);
     return {
         headers: [["authorization", Redacted.make(`Bearer ${Redacted.value(token)}`)]],
-        tls
+        tls,
+        proxy
     };
 });
 export const resolveUsernameToken = (source, token) => token === undefined
@@ -175,5 +289,13 @@ export const nodeSecretSource = (environment = process.env) => ({
     readFile: (path) => Effect.tryPromise({
         try: async () => new Uint8Array(await readFile(path)),
         catch: () => new AuthProfileError({ subject: `file:${path}`, detail: "not readable" })
+    }),
+    readPemDirectory: (path) => Effect.tryPromise({
+        try: async () => {
+            const names = (await readdir(path)).filter((name) => /\.(pem|crt|cer)$/i.test(name)).sort();
+            const parts = await Promise.all(names.map((name) => readFile(join(path, name))));
+            return concatPem(...parts.map((part) => new Uint8Array(part)));
+        },
+        catch: () => new AuthProfileError({ subject: `tls.caDir ${path}`, detail: "not readable" })
     })
 });

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

@@ -7,7 +7,7 @@ import { resolveSide, resolveUsernameToken } from "./Auth.js";
 import { checkCall } from "./CallPolicy.js";
 import { elementByName, operationByName } from "./Catalog.js";
 import { effectiveClass } from "./Classification.js";
-import { buildEnvelope, readEnvelope, safeHeaders, soapHeaders, stripSecurity, usernameTokenHeader } from "./Envelope.js";
+import { buildEnvelope, readEnvelope, safeHeaders, soapHeaders, securityHeader, stripSecurity } from "./Envelope.js";
 import { instanceFromXml, instanceToXml, validateInstance } from "./Instance.js";
 import { kindsFromCatalog, maskDocument, MaskingReport, mergeReports } from "./Masking.js";
 import { Exchange, issueRecords, loadMaskingKey, loadMaskingOverrides, readRequestFile, RecordedMessage, RecordedResponse, samplePaths, writeExchange } from "./Samples.js";
@@ -92,12 +92,23 @@ export const callOperation = (options) => Effect.gen(function* () {
         });
     }
     const side = yield* resolveSide(options.secrets, profile.call);
-    const token = yield* resolveUsernameToken(options.secrets, profile.wsSecurity);
+    const usernameToken = yield* resolveUsernameToken(options.secrets, profile.wsSecurity);
     const now = options.now ?? (() => new Date());
     const random = options.random ?? ((size) => new Uint8Array(randomBytes(size)));
-    const header = token === undefined
-        ? undefined
-        : usernameTokenHeader(token, { nonce: random(16), created: now().toISOString() });
+    if (profile.sts !== undefined && options.token === undefined) {
+        return yield* new CallSetupError({
+            operation: operation.name,
+            detail: "the profile names an STS but the call has no token source"
+        });
+    }
+    const saml = options.token === undefined ? undefined : yield* options.token.current;
+    const created = now().toISOString();
+    const header = securityHeader({
+        ...(usernameToken === undefined ? {} : { usernameToken }),
+        ...(saml === undefined ? {} : { token: saml.token }),
+        ...(profile.sts?.timestamp === false || saml === undefined ? {} : { timestamp: { created } }),
+        material: { nonce: random(16), created }
+    });
     const bodyXml = instanceToXml(catalog, input, request.body);
     const envelope = buildEnvelope(operation.soapVersion, bodyXml, header);
     const headers = soapHeaders(operation.soapVersion, operation.soapAction);
@@ -108,6 +119,7 @@ export const callOperation = (options) => Effect.gen(function* () {
         secretHeaders: side.headers,
         body: envelope,
         ...(side.tls === undefined ? {} : { tls: side.tls }),
+        ...(side.proxy === undefined ? {} : { proxy: side.proxy }),
         timeout: Duration.seconds(profile.timeoutSeconds ?? 60)
     });
     const key = yield* loadMaskingKey(workspace, service, random);