@llm4ts/shell 2.27.0 → 2.28.0

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);

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

@@ -2,7 +2,7 @@ import { basename } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { ComplexTypeDef, elementByName, localName, splitClark, typeByName, WsdlCatalog } from "./Catalog.js";
-import { decodeAuthProfile } from "./Auth.js";
+import { AuthProfileError, decodeAuthProfile, profileFileName } from "./Auth.js";
 import { classifyOperations, operationsDrift, parseOperationsFile, renderOperationsFile } from "./Classification.js";
 import { readCatalog } from "./Wsdl.js";
 // `soap-discover` as a library call: read the catalog, persist it with a
@@ -26,10 +26,14 @@ export const servicePaths = (service) => {
         summary: `${directory}/catalog.md`,
         operations: `${directory}/operations.md`,
         auth: `${directory}/auth.json`,
+        /** Captured server chains, one PEM per host (`trust`). */
+        trustDir: `${directory}/trust`,
         masking: `${directory}/masking.json`,
         gitignore: `${directory}/.gitignore`
     };
 };
+/** The profile file an environment selects: `auth.json`, or `auth.<env>.json`. */
+export const profilePath = (service, env) => `${serviceDirectory(service)}/${profileFileName(env)}`;
 /** A directory-safe service name: explicit, else the WSDL's service, else the file name. */
 export const serviceName = (catalog, location, explicit) => {
     const raw = explicit ??
@@ -39,8 +43,32 @@ export const serviceName = (catalog, location, explicit) => {
     return safe === "" ? "service" : safe;
 };
 /** What never leaves the machine: credentials references, raw captures, the masking key. */
-export const serviceGitignore = ["auth.json", "raw/", ".masking-key", ""].join("\n");
-export const loadAuthProfile = (workspace, service) => Effect.flatMap(readIfPresent(workspace, servicePaths(service).auth), (text) => text === undefined ? Effect.succeed(undefined) : decodeAuthProfile(text));
+export const serviceGitignore = [
+    "auth.json",
+    "auth.*.json",
+    "trust/",
+    "raw/",
+    ".masking-key",
+    ""
+].join("\n");
+/**
+ * The profile of the selected environment (`LLM4TS_SOAP_ENV` / `--env`):
+ * `auth.<env>.json` when one is named, which must then exist; else `auth.json`.
+ */
+export const loadAuthProfile = (workspace, service, env) => Effect.gen(function* () {
+    const path = profilePath(service, env);
+    const text = yield* readIfPresent(workspace, path);
+    if (text === undefined) {
+        if (env !== undefined && env.trim() !== "") {
+            return yield* new AuthProfileError({
+                subject: path,
+                detail: `no profile for environment '${env.trim()}'; write it, or unset LLM4TS_SOAP_ENV`
+            });
+        }
+        return undefined;
+    }
+    return yield* decodeAuthProfile(text, path.split("/").at(-1) ?? "auth.json");
+});
 export const readIfPresent = (workspace, path) => Effect.flatMap(workspace.discover(path), (found) => found.includes(path) ? workspace.read(path) : Effect.succeed(undefined));
 export const encodeCatalog = (catalog) => `${JSON.stringify(Schema.encodeSync(WsdlCatalog)(catalog), null, 2)}\n`;
 export const loadCatalog = (workspace, service) => {

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

@@ -25,21 +25,46 @@ export const passwordDigest = (material, password) => createHash("sha1")
     .update(material.created, "utf8")
     .update(password, "utf8")
     .digest("base64");
-export const usernameTokenHeader = (token, material) => {
+const usernameTokenElement = (token, material) => {
     const password = Redacted.value(token.password);
     const passwordValue = token.passwordType === "digest" ? passwordDigest(material, password) : password;
     const type = token.passwordType === "digest" ? "PasswordDigest" : "PasswordText";
-    return Redacted.make([
-        `<wsse:Security xmlns:wsse="${WsseNamespace}" xmlns:wsu="${WsuNamespace}" soapenv:mustUnderstand="1">`,
+    return [
         '<wsse:UsernameToken wsu:Id="UsernameToken-1">',
         `<wsse:Username>${escapeText(token.user)}</wsse:Username>`,
         `<wsse:Password Type="${TokenProfile}#${type}">${escapeText(passwordValue)}</wsse:Password>`,
         `<wsse:Nonce EncodingType="${Base64Binary}">${Buffer.from(material.nonce).toString("base64")}</wsse:Nonce>`,
         `<wsu:Created>${material.created}</wsu:Created>`,
-        "</wsse:UsernameToken>",
+        "</wsse:UsernameToken>"
+    ].join("");
+};
+const fiveMinutesAfter = (created) => new Date(new Date(created).getTime() + 5 * 60_000).toISOString();
+/**
+ * The WS-Security header, in the order ESBs expect: Timestamp, then the
+ * UsernameToken, then the bearer token. Empty parts are left out; no parts
+ * at all gives no header.
+ */
+export const securityHeader = (parts) => {
+    const inner = [];
+    if (parts.timestamp !== undefined) {
+        inner.push('<wsu:Timestamp wsu:Id="TS-1">', `<wsu:Created>${parts.timestamp.created}</wsu:Created>`, `<wsu:Expires>${parts.timestamp.expires ?? fiveMinutesAfter(parts.timestamp.created)}</wsu:Expires>`, "</wsu:Timestamp>");
+    }
+    if (parts.usernameToken !== undefined) {
+        inner.push(usernameTokenElement(parts.usernameToken, parts.material));
+    }
+    if (parts.token !== undefined) {
+        inner.push(Redacted.value(parts.token));
+    }
+    if (inner.length === 0) {
+        return undefined;
+    }
+    return Redacted.make([
+        `<wsse:Security xmlns:wsse="${WsseNamespace}" xmlns:wsu="${WsuNamespace}" soapenv:mustUnderstand="1">`,
+        ...inner,
         "</wsse:Security>"
     ].join(""));
 };
+export const usernameTokenHeader = (token, material) => securityHeader({ usernameToken: token, material }) ?? Redacted.make("");
 /**
  * Wrap a body element (serialized XML, carrying its own namespace
  * declarations) in an envelope. The header, when present, is secret

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

@@ -247,6 +247,7 @@ export const exploreService = (options) => Effect.gen(function* () {
             operations: probeFile,
             secrets: options.secrets,
             transport: options.transport,
+            ...(options.token === undefined ? {} : { token: options.token }),
             allowMutating: undefined,
             confirm: () => Effect.succeed(false),
             ...(body === undefined