@wirebench/engine 2.1.1

package/dist/send.js

@@ -0,0 +1,210 @@
+/**
+ * Sends an already-built SOAP envelope over HTTP and structurally parses the
+ * response: SOAP version, fault, or "not actually SOAP" detection.
+ */
+import { randomUUID } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
+import { WirebenchError } from './errors.js';
+import { expandSendInput } from './project/properties.js';
+import { sendWithAuth } from './http/auth/apply.js';
+import { headerValue, mergeHeaders } from './http/headers.js';
+import { charsetOf } from './soap/charset.js';
+import { packageRequestBody, readResponseBody, substituteInlineFiles, } from './soap/mime/send-pipeline.js';
+import { parseSoapResponse } from './soap/response-parser.js';
+import { soapActionHeaders } from './soap/soap-action.js';
+import { applyWsaHeaders, effectiveAction } from './wsa/headers.js';
+import { applyOutgoingWss } from './wss/apply.js';
+import { processIncomingWss } from './wss/incoming/index.js';
+/**
+ * Sends `input.envelopeXml` to `input.endpoint` over HTTP, computing the
+ * `Content-Type`/`SOAPAction` headers for `input.soapVersion` and merging in
+ * any caller-supplied `input.headers`, which override the computed ones.
+ *
+ * HTTP-layer failures (timeout, abort, DNS, TLS, ...) propagate as
+ * {@link HttpError}; a non-2xx HTTP status is not an error and is returned
+ * as a normal exchange for the caller to inspect.
+ *
+ * When `input.attachmentOptions` is given, the envelope additionally goes through the
+ * attachment pipeline. Its stages are split across the send: inline `file:` references are
+ * substituted up front, with property expansion (they are envelope text, and WS-Security must
+ * sign what is actually sent), while MTOM and then SwA package the finished envelope after the
+ * WS-Addressing and WS-Security rewrites. A `multipart/related` response is unwrapped into its
+ * envelope plus `response.attachments`. See `soap/mime/send-pipeline.ts`.
+ *
+ * The full request order is: property expansion → inline files → WS-Addressing → WS-Security →
+ * MTOM → SwA → gzip.
+ *
+ * When `options.scopes` is given, `input.endpoint`, `input.envelopeXml`,
+ * `input.soapAction` and every header name/value are first passed through
+ * {@link expandSendInput}; any expressions that could not be resolved are
+ * left verbatim in the sent request and reported on the returned exchange's
+ * `unresolved` field, rather than failing the send.
+ *
+ * When `input.auth` is Basic, the `Authorization` header is either sent up front
+ * (`preemptive`) or added on a single retry after the server answers the first attempt
+ * with a 401 `Basic` challenge; both attempts share the one `timeoutMs` budget (if the first
+ * attempt already used it all, the challenge is reported as-is, `attempts: 1`, rather than
+ * firing a retry doomed to time out immediately) and the returned exchange is the final attempt
+ * actually made. A caller-supplied `Authorization` header always wins.
+ *
+ * When `input.auth` is NTLM, the send instead runs the three-leg NTLMv2 handshake over one
+ * dedicated connection (`http/auth/ntlm-transport.ts`): a bare bodyless leg, the Type 1
+ * message, then the Type 3 message carrying the real body. The returned exchange is the
+ * final leg, `durationMs` sums every leg, and a server that never challenges short-circuits
+ * after the first (`attempts: 1`).
+ *
+ * @param input the endpoint, envelope and transport options to send
+ * @param options an injected `dispatcher` (tests), `now` clock, and/or property `scopes`
+ */
+export async function sendSoapRequest(input, options) {
+    let unresolved;
+    let effectiveInput = input;
+    if (options?.scopes !== undefined) {
+        const expanded = expandSendInput(input, options.scopes, { entitize: input.entitize ?? false });
+        effectiveInput = expanded.input;
+        unresolved = expanded.unresolved;
+    }
+    const problems = [];
+    // Inline `file:` references are substituted first, with property expansion: both are envelope
+    // *text* preparation, and the envelope every later stage sees must be the one that goes on
+    // the wire. Doing it after WS-Security — as this pipeline used to — signed the literal
+    // `file:/…` text and then replaced it, leaving a signature that verifies over nothing that
+    // was sent. MTOM/SwA still run last, after WSS, so the header is inside the packaged envelope.
+    const inlinedEnvelopeXml = await substituteInlineFiles(effectiveInput, problems);
+    if (inlinedEnvelopeXml !== effectiveInput.envelopeXml) {
+        effectiveInput = { ...effectiveInput, envelopeXml: inlinedEnvelopeXml };
+    }
+    // WS-Addressing runs first of the envelope rewrites: before WS-Security, so a signature
+    // configured to cover the `wsa:*` headers finds them already in place, and before the
+    // attachment pipeline, so they are inside the envelope MTOM/SwA package and raw capture show.
+    let wsaApplied;
+    const wsa = effectiveInput.wsa;
+    if (wsa !== undefined && wsa.config.enabled) {
+        let messageId;
+        const uuid = wsa.uuid ?? (() => randomUUID());
+        const envelopeXml = applyWsaHeaders(effectiveInput.envelopeXml, wsa.config, {
+            endpoint: effectiveInput.endpoint,
+            ...(effectiveInput.soapAction !== undefined ? { soapAction: effectiveInput.soapAction } : {}),
+            defaultAction: wsa.defaultAction,
+            uuid: () => {
+                const value = uuid();
+                messageId = `urn:uuid:${value}`;
+                return value;
+            },
+            envelopeVersion: effectiveInput.soapVersion,
+        });
+        const action = effectiveAction(wsa.config, {
+            ...(effectiveInput.soapAction !== undefined ? { soapAction: effectiveInput.soapAction } : {}),
+            defaultAction: wsa.defaultAction,
+        });
+        // A fixed MessageID never goes through the uuid factory, so read it back off the config.
+        const fixed = wsa.config.messageId;
+        if (messageId === undefined && fixed !== undefined && fixed.length > 0 && fixed !== 'auto') {
+            messageId = fixed;
+        }
+        effectiveInput = { ...effectiveInput, envelopeXml };
+        wsaApplied = {
+            ...(messageId !== undefined ? { messageId } : {}),
+            ...(action !== undefined ? { action } : {}),
+        };
+    }
+    // WS-Security runs on the expanded envelope and before the attachment pipeline, so the
+    // header is inside the envelope that MTOM/SwA package and that raw capture records.
+    let wssApplied;
+    const wss = effectiveInput.wss;
+    if (wss?.outgoing !== undefined) {
+        const envelopeXml = await applyOutgoingWss(effectiveInput.envelopeXml, wss.outgoing, wss.ctx, {
+            ...(wss.requestProperties !== undefined ? { requestProperties: wss.requestProperties } : {}),
+        });
+        effectiveInput = { ...effectiveInput, envelopeXml };
+        wssApplied = wss.outgoing.entries.map((entry) => entry.kind);
+    }
+    const charset = charsetOf(effectiveInput.headers !== undefined ? headerValue(effectiveInput.headers, 'content-type') : undefined) ??
+        'UTF-8';
+    const computed = soapActionHeaders(effectiveInput.soapVersion, effectiveInput.soapAction, {
+        ...(effectiveInput.skipSoapAction !== undefined ? { skipSoapAction: effectiveInput.skipSoapAction } : {}),
+        charset,
+    });
+    const headers = mergeHeaders({ 'content-type': computed.contentType, ...computed.headers }, effectiveInput.headers ?? {});
+    // Attachments are packaged before compression, so gzip applies to the whole multipart
+    // body exactly as it would to a plain envelope.
+    const encoded = await packageRequestBody(effectiveInput, headers);
+    // Compression is applied after the headers are merged so a caller-supplied Content-Encoding
+    // cannot silently disagree with what is actually on the wire.
+    const body = effectiveInput.compressBody === 'gzip' ? new Uint8Array(gzipSync(encoded)) : encoded;
+    if (effectiveInput.compressBody === 'gzip') {
+        headers['content-encoding'] = 'gzip';
+    }
+    const timeoutMs = effectiveInput.timeoutMs ?? 60_000;
+    const request = {
+        url: effectiveInput.endpoint,
+        method: 'POST',
+        headers,
+        body,
+        timeoutMs,
+        followRedirects: effectiveInput.followRedirects ?? false,
+        ...(effectiveInput.maxSizeBytes !== undefined ? { maxSizeBytes: effectiveInput.maxSizeBytes } : {}),
+        ...(effectiveInput.localAddress !== undefined ? { localAddress: effectiveInput.localAddress } : {}),
+        ...(effectiveInput.signal !== undefined ? { signal: effectiveInput.signal } : {}),
+        ...(effectiveInput.tls !== undefined ? { tls: effectiveInput.tls } : {}),
+        ...(effectiveInput.proxy !== undefined ? { proxy: effectiveInput.proxy } : {}),
+        ...(effectiveInput.allowH2 !== undefined ? { allowH2: effectiveInput.allowH2 } : {}),
+    };
+    // Basic (preemptive or challenged) and NTLM are transport concerns, shared with the REST send.
+    const authenticated = await sendWithAuth(request, effectiveInput.auth, options);
+    const http = authenticated.http;
+    const totalDurationMs = authenticated.durationMs;
+    const authSummary = authenticated.auth;
+    const { envelopeXml: receivedXml, attachments } = readResponseBody(http.body, headerValue(http.headers, 'content-type'), effectiveInput.attachmentOptions, problems);
+    // Incoming WS-Security runs on the envelope the response pipeline produced — after MTOM
+    // expansion — so a signature over an expanded Body is judged over what the user sees.
+    let wssIncoming;
+    let envelopeXml = receivedXml;
+    if (wss?.incoming !== undefined) {
+        wssIncoming = await processIncomingWss(receivedXml, wss.incoming, wss.ctx);
+        if (wssIncoming.decryptedXml !== undefined) {
+            envelopeXml = wssIncoming.decryptedXml;
+        }
+    }
+    let response;
+    try {
+        const parsed = parseSoapResponse(envelopeXml);
+        response = {
+            envelopeXml,
+            version: parsed.version,
+            ...(parsed.fault !== undefined ? { fault: parsed.fault } : {}),
+            isSoap: true,
+            ...(attachments !== undefined ? { attachments } : {}),
+        };
+    }
+    catch (cause) {
+        if (cause instanceof WirebenchError && cause.code === 'not-a-soap-envelope') {
+            response = { envelopeXml, isSoap: false, ...(attachments !== undefined ? { attachments } : {}) };
+            problems.push({ code: 'not-soap', message: cause.message });
+        }
+        else if (cause instanceof WirebenchError && cause.code === 'xml-parse-error') {
+            response = { envelopeXml, isSoap: false, ...(attachments !== undefined ? { attachments } : {}) };
+            problems.push({ code: 'xml-parse-error', message: cause.message });
+        }
+        else {
+            throw cause;
+        }
+    }
+    return {
+        http,
+        ...(response !== undefined ? { response } : {}),
+        durationMs: totalDurationMs,
+        ...(authSummary !== undefined ? { auth: authSummary } : {}),
+        problems,
+        ...(unresolved !== undefined ? { unresolved } : {}),
+        ...(wsaApplied !== undefined ? { wsa: wsaApplied } : {}),
+        ...(wssApplied !== undefined || wssIncoming !== undefined
+            ? {
+                wss: {
+                    ...(wssApplied !== undefined ? { applied: wssApplied } : {}),
+                    ...(wssIncoming !== undefined ? { incoming: wssIncoming } : {}),
+                },
+            }
+            : {}),
+    };
+}

package/dist/soap/body-builder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turns WSDL message parts into the XML that goes inside `soapenv:Body` and
+ * `soapenv:Header`, following the WSDL 1.1 SOAP binding and the WS-I Basic
+ * Profile conventions for `document`/`rpc` × `literal`/`encoded`.
+ */
+import type { Message, Part, SoapBody, SoapHeader, WsdlDefinition } from '../wsdl/model.js';
+import type { GenerateOptions } from '../xsd/sample-generator.js';
+import type { SchemaSet } from '../xsd/schema-set.js';
+import type { BuildProblem } from './build-problems.js';
+import type { NamespaceScope } from './namespace-scope.js';
+/** Everything the body/header builders need, plus the problem sink they append to. */
+export interface BodyBuildContext {
+    readonly definition: WsdlDefinition;
+    readonly schemaSet: SchemaSet;
+    readonly scope: NamespaceScope;
+    readonly genOptions: Partial<GenerateOptions>;
+    readonly indent: string;
+    readonly problems: BuildProblem[];
+}
+/**
+ * Generates the fragment for one part in `document` style (and for header
+ * parts, which are always element-like whatever the body style is).
+ *
+ * A part declaring a `type` rather than an `element` is not WS-I conformant,
+ * but is common in the wild; the part's own name is then used as the
+ * (unqualified) element name and no problem is reported.
+ */
+export declare function buildDocumentPart(ctx: BodyBuildContext, part: Part): string | undefined;
+/** Selects and orders the parts a body carries: `soap:body/@parts` first, then `parameterOrder`. */
+export declare function orderParts(parts: readonly Part[], bodyParts: readonly string[] | undefined, parameterOrder: readonly string[] | undefined): readonly Part[];
+/**
+ * Builds the content of `soapenv:Body` for one binding operation.
+ *
+ * @param style the effective operation style (`soap:operation/@style` falling back to `soap:binding/@style`)
+ */
+export declare function buildBody(ctx: BodyBuildContext, operationName: string, style: 'document' | 'rpc', body: SoapBody, message: Message, parameterOrder: readonly string[] | undefined): string;
+/** Builds the content of `soapenv:Header` from a binding operation's `soap:header` elements. */
+export declare function buildHeaders(ctx: BodyBuildContext, headers: readonly SoapHeader[]): string;

package/dist/soap/body-builder.js

@@ -0,0 +1,250 @@
+/**
+ * Turns WSDL message parts into the XML that goes inside `soapenv:Body` and
+ * `soapenv:Header`, following the WSDL 1.1 SOAP binding and the WS-I Basic
+ * Profile conventions for `document`/`rpc` × `literal`/`encoded`.
+ */
+import { SchemaError } from '../errors.js';
+import { NS } from '../xml/namespaces.js';
+import { findMessage } from '../wsdl/model.js';
+import { qnameToString } from '../wsdl/qname.js';
+import { generateElement, generateSoapEncArray, generateType } from '../xsd/sample-generator.js';
+import { arrayTypeOf } from '../xsd/sample-types.js';
+import { escapeAttribute } from '../xsd/xml-writer.js';
+import { SOAP_ENVELOPE_PREFIX } from './envelope.js';
+/** Inserts attributes into a fragment's root start tag. */
+function addRootAttributes(xml, attributes) {
+    if (attributes.length === 0) {
+        return xml;
+    }
+    const rendered = attributes.map(([name, value]) => ` ${name}="${escapeAttribute(value)}"`).join('');
+    // Attribute values are `>`-escaped by the writer, so the first `>` on the
+    // first line always terminates the start tag.
+    const close = xml.indexOf('>');
+    if (close === -1) {
+        return xml;
+    }
+    const insertAt = xml[close - 1] === '/' ? close - 1 : close;
+    return `${xml.slice(0, insertAt)}${rendered}${xml.slice(insertAt)}`;
+}
+/**
+ * Removes the `xmlns:*` declarations a fragment put on its own root, for every
+ * prefix the envelope now declares with the same URI. A declaration the
+ * envelope does not carry is left alone rather than silently dropped.
+ */
+function stripHoistedNamespaces(xml, scope) {
+    const close = xml.indexOf('>');
+    if (close === -1) {
+        return xml;
+    }
+    const startTag = xml.slice(0, close);
+    const stripped = startTag.replace(/ xmlns:([A-Za-z_][\w.-]*)="([^"]*)"/g, (match, prefix, uri) => scope.declares(prefix, uri) ? '' : match);
+    return `${stripped}${xml.slice(close)}`;
+}
+/** Prepends `pad` to every non-empty line. */
+function indentLines(xml, pad) {
+    return xml
+        .split('\n')
+        .map((line) => (line.length === 0 ? line : `${pad}${line}`))
+        .join('\n');
+}
+/** Registers a fragment's namespaces on the envelope and drops its own declarations. */
+function hoist(ctx, fragment) {
+    ctx.scope.markUsed(fragment.namespaces);
+    return stripHoistedNamespaces(fragment.xml, ctx.scope);
+}
+function generateOptions(ctx) {
+    return { ...ctx.genOptions, indent: ctx.indent, prefixes: ctx.scope.prefixes() };
+}
+/** True when `type` is neither a built-in nor a global type in the schema set. */
+function isUnknownType(ctx, type) {
+    return ctx.schemaSet.builtin(type) === undefined && ctx.schemaSet.lookupType(type) === undefined;
+}
+/**
+ * Generates the fragment for one part in `document` style (and for header
+ * parts, which are always element-like whatever the body style is).
+ *
+ * A part declaring a `type` rather than an `element` is not WS-I conformant,
+ * but is common in the wild; the part's own name is then used as the
+ * (unqualified) element name and no problem is reported.
+ */
+export function buildDocumentPart(ctx, part) {
+    if (part.element !== undefined) {
+        try {
+            return hoist(ctx, generateElement(ctx.schemaSet, part.element, generateOptions(ctx)));
+        }
+        catch (error) {
+            if (error instanceof SchemaError) {
+                ctx.problems.push({
+                    code: 'unknown-element',
+                    message: `Part "${part.name}" references undeclared element ${qnameToString(part.element)}`,
+                });
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    if (part.type !== undefined) {
+        if (isUnknownType(ctx, part.type)) {
+            ctx.problems.push({
+                code: 'unknown-type',
+                message: `Part "${part.name}" references undeclared type ${qnameToString(part.type)}`,
+            });
+        }
+        const name = { namespaceUri: '', localName: part.name };
+        return hoist(ctx, generateType(ctx.schemaSet, name, part.type, generateOptions(ctx)));
+    }
+    ctx.problems.push({ code: 'missing-part', message: `Part "${part.name}" declares neither an element nor a type` });
+    return undefined;
+}
+/** The SOAP-encoded array item type a part's type declares, if it is one. */
+function soapEncItemType(ctx, type) {
+    const definition = ctx.schemaSet.lookupType(type);
+    if (definition === undefined ||
+        definition.kind !== 'complexType' ||
+        definition.content.kind !== 'complexContent' ||
+        ctx.schemaSet.builtin(definition.content.base)?.soapEncArray !== true) {
+        return undefined;
+    }
+    const raw = arrayTypeOf(ctx.schemaSet.resolveContent(definition).attributes);
+    if (raw === undefined) {
+        return { namespaceUri: NS.XSD, localName: 'anyType' };
+    }
+    // `wsdl:arrayType` is a QName-plus-bounds, e.g. `xsd:int[]` or `tns:Item[,]`.
+    const withoutBounds = raw.replace(/(\[[^\]]*\])+\s*$/, '').trim();
+    const colon = withoutBounds.indexOf(':');
+    if (colon === -1) {
+        return { namespaceUri: NS.XSD, localName: 'anyType' };
+    }
+    const prefix = withoutBounds.slice(0, colon);
+    const localName = withoutBounds.slice(colon + 1);
+    // The prefix was in scope on the schema element, whose declarations are not
+    // kept; the root `wsdl:definitions` declarations are the practical stand-in.
+    const namespaceUri = ctx.definition.namespaceDeclarations[prefix];
+    return namespaceUri === undefined || localName === ''
+        ? { namespaceUri: NS.XSD, localName: 'anyType' }
+        : { namespaceUri, localName };
+}
+/** Builds one rpc accessor: an unqualified element named after the part. */
+function buildRpcAccessor(ctx, part, use) {
+    const name = { namespaceUri: '', localName: part.name };
+    if (part.element !== undefined) {
+        // A part with an `element` is non-WS-I for rpc (R2203); emit the element
+        // itself as the accessor rather than inventing a wrapper around it.
+        return buildDocumentPart(ctx, part);
+    }
+    if (part.type === undefined) {
+        ctx.problems.push({ code: 'missing-part', message: `Part "${part.name}" declares neither an element nor a type` });
+        return undefined;
+    }
+    if (isUnknownType(ctx, part.type)) {
+        ctx.problems.push({
+            code: 'unknown-type',
+            message: `Part "${part.name}" references undeclared type ${qnameToString(part.type)}`,
+        });
+    }
+    const itemType = soapEncItemType(ctx, part.type);
+    const fragment = itemType !== undefined
+        ? generateSoapEncArray(ctx.schemaSet, name, itemType, generateOptions(ctx))
+        : generateType(ctx.schemaSet, name, part.type, generateOptions(ctx));
+    const xml = hoist(ctx, fragment);
+    if (use !== 'encoded' || itemType !== undefined) {
+        return xml;
+    }
+    // SOAP encoding wants every simple-typed accessor self-describing.
+    const builtin = ctx.schemaSet.builtin(part.type);
+    const resolved = ctx.schemaSet.lookupType(part.type);
+    if (builtin === undefined && resolved?.kind !== 'simpleType') {
+        return xml;
+    }
+    const typeLabel = `${ctx.scope.use(part.type.namespaceUri)}:${part.type.localName}`;
+    return addRootAttributes(xml, [[`${ctx.scope.use(NS.XSI)}:type`, typeLabel]]);
+}
+/** Selects and orders the parts a body carries: `soap:body/@parts` first, then `parameterOrder`. */
+export function orderParts(parts, bodyParts, parameterOrder) {
+    const selected = bodyParts === undefined
+        ? [...parts]
+        : bodyParts.flatMap((name) => {
+            const match = parts.find((part) => part.name === name);
+            return match === undefined ? [] : [match];
+        });
+    if (parameterOrder === undefined) {
+        return selected;
+    }
+    const ordered = parameterOrder.flatMap((name) => {
+        const match = selected.find((part) => part.name === name);
+        return match === undefined ? [] : [match];
+    });
+    // Parts the port type did not name (typically the return part) keep their
+    // message order and follow the named ones, per WSDL 1.1 §2.4.5.
+    return [...ordered, ...selected.filter((part) => !ordered.includes(part))];
+}
+/** Builds the `soapenv:Body` content for a `document`-style operation. */
+function buildDocumentBody(ctx, parts) {
+    return parts
+        .map((part) => buildDocumentPart(ctx, part))
+        .filter((xml) => xml !== undefined)
+        .join('\n');
+}
+/** Builds the `soapenv:Body` content for an `rpc`-style operation: one wrapper, one child per part. */
+function buildRpcBody(ctx, operationName, body, parts) {
+    const wrapperNamespace = body.namespace ?? ctx.definition.targetNamespace;
+    const prefix = ctx.scope.use(wrapperNamespace);
+    const tag = prefix === '' ? operationName : `${prefix}:${operationName}`;
+    const attributes = body.use === 'encoded'
+        ? ` ${SOAP_ENVELOPE_PREFIX}:encodingStyle="${escapeAttribute(body.encodingStyle ?? NS.SOAP11_ENC)}"`
+        : '';
+    const accessors = parts
+        .map((part) => buildRpcAccessor(ctx, part, body.use))
+        .filter((xml) => xml !== undefined);
+    if (accessors.length === 0) {
+        return `<${tag}${attributes}/>`;
+    }
+    return [`<${tag}${attributes}>`, ...accessors.map((xml) => indentLines(xml, ctx.indent)), `</${tag}>`].join('\n');
+}
+/**
+ * Builds the content of `soapenv:Body` for one binding operation.
+ *
+ * @param style the effective operation style (`soap:operation/@style` falling back to `soap:binding/@style`)
+ */
+export function buildBody(ctx, operationName, style, body, message, parameterOrder) {
+    const parts = orderParts(message.parts, body.parts, style === 'rpc' ? parameterOrder : undefined);
+    for (const name of body.parts ?? []) {
+        if (!message.parts.some((part) => part.name === name)) {
+            ctx.problems.push({
+                code: 'missing-part',
+                message: `soap:body names part "${name}", which message ${qnameToString(message.name)} does not declare`,
+            });
+        }
+    }
+    return style === 'rpc' ? buildRpcBody(ctx, operationName, body, parts) : buildDocumentBody(ctx, parts);
+}
+/** Builds the content of `soapenv:Header` from a binding operation's `soap:header` elements. */
+export function buildHeaders(ctx, headers) {
+    const fragments = [];
+    for (const header of headers) {
+        const message = findMessage(ctx.definition, header.message);
+        if (message === undefined) {
+            ctx.problems.push({
+                code: 'missing-message',
+                message: `soap:header references unknown message ${qnameToString(header.message)}`,
+            });
+            continue;
+        }
+        const part = message.parts.find((candidate) => candidate.name === header.part);
+        if (part === undefined) {
+            ctx.problems.push({
+                code: 'missing-part',
+                message: `soap:header references part "${header.part}", which message ${qnameToString(message.name)} does not declare`,
+            });
+            continue;
+        }
+        const xml = buildDocumentPart(ctx, part);
+        if (xml === undefined) {
+            continue;
+        }
+        fragments.push(header.use === 'encoded'
+            ? addRootAttributes(xml, [[`${SOAP_ENVELOPE_PREFIX}:encodingStyle`, header.encodingStyle ?? NS.SOAP11_ENC]])
+            : xml);
+    }
+    return fragments.join('\n');
+}

package/dist/soap/build-problems.d.ts

@@ -0,0 +1,12 @@
+/** Non-fatal problems the sample-request builder reports instead of throwing. */
+/** Machine-readable kinds of {@link BuildProblem}. */
+export type BuildProblemCode = 'unknown-operation' | 'unknown-binding' | 'unsupported-binding' | 'missing-part' | 'unknown-element' | 'unknown-type' | 'missing-portType' | 'missing-message';
+/**
+ * A problem encountered while building a sample request. The builder is
+ * deliberately total — it always returns an envelope, however degraded — so
+ * the UI can show a partial request alongside what is wrong with it.
+ */
+export interface BuildProblem {
+    readonly code: BuildProblemCode;
+    readonly message: string;
+}

package/dist/soap/build-problems.js

@@ -0,0 +1,2 @@
+/** Non-fatal problems the sample-request builder reports instead of throwing. */
+export {};

package/dist/soap/charset.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Turning a SOAP envelope into wire bytes and back, per the request's encoding and the
+ * response's declared charset.
+ */
+/** The charset declared in a `Content-Type` header value, if any. */
+export declare function charsetOf(contentType: string | undefined): string | undefined;
+/**
+ * Encodes `text` for the wire, per `encoding` (default utf-8).
+ *
+ * `ISO-8859-1` is a valid encoding label (it is one of the choices the Encoding
+ * property's `<select>` shows), but it is not one of the labels Node's `Buffer` recognises —
+ * `iso-8859-1` is instead spelled `latin1` there. That is the one label this function
+ * translates; every other name is handed to `Buffer` as-is.
+ */
+export declare function encodeBody(text: string, encoding: string | undefined): Uint8Array;
+/** Decodes a response body per its `Content-Type` charset (default UTF-8), falling back to UTF-8 with a `decode-error` problem when the charset label is unsupported or the bytes are invalid for it. */
+export declare function decodeBody(body: Uint8Array, contentType: string | undefined): {
+    text: string;
+    problem?: {
+        readonly code: 'decode-error';
+        readonly message: string;
+    };
+};

package/dist/soap/charset.js

@@ -0,0 +1,47 @@
+/**
+ * Turning a SOAP envelope into wire bytes and back, per the request's encoding and the
+ * response's declared charset.
+ */
+import { WirebenchError } from '../errors.js';
+/** The charset declared in a `Content-Type` header value, if any. */
+export function charsetOf(contentType) {
+    const match = contentType !== undefined ? /charset=([^;]+)/i.exec(contentType) : null;
+    return match?.[1]?.trim().replace(/^"|"$/g, '');
+}
+/**
+ * Encodes `text` for the wire, per `encoding` (default utf-8).
+ *
+ * `ISO-8859-1` is a valid encoding label (it is one of the choices the Encoding
+ * property's `<select>` shows), but it is not one of the labels Node's `Buffer` recognises —
+ * `iso-8859-1` is instead spelled `latin1` there. That is the one label this function
+ * translates; every other name is handed to `Buffer` as-is.
+ */
+export function encodeBody(text, encoding) {
+    const normalized = (encoding ?? 'utf-8').toLowerCase();
+    if (normalized === 'utf-8' || normalized === 'utf8') {
+        return new TextEncoder().encode(text);
+    }
+    const bufferEncoding = normalized === 'iso-8859-1' ? 'latin1' : normalized;
+    if (Buffer.isEncoding(bufferEncoding)) {
+        return new Uint8Array(Buffer.from(text, bufferEncoding));
+    }
+    throw new WirebenchError('unsupported-encoding', `Unsupported request encoding "${encoding}"`, {
+        details: { encoding },
+    });
+}
+/** Decodes a response body per its `Content-Type` charset (default UTF-8), falling back to UTF-8 with a `decode-error` problem when the charset label is unsupported or the bytes are invalid for it. */
+export function decodeBody(body, contentType) {
+    const label = charsetOf(contentType) ?? 'utf-8';
+    try {
+        return { text: new TextDecoder(label, { fatal: false }).decode(body) };
+    }
+    catch {
+        return {
+            text: new TextDecoder('utf-8', { fatal: false }).decode(body),
+            problem: {
+                code: 'decode-error',
+                message: `Response charset "${label}" is not supported; decoded as UTF-8 instead`,
+            },
+        };
+    }
+}

package/dist/soap/envelope.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SOAP envelope assembly: wraps already-rendered header and body fragments in
+ * a `soapenv:Envelope`, following the conventions classic SOAP workbenches
+ * produce (three-space indent, `soapenv` prefix, an always-present `Header`).
+ */
+import type { Document } from '@xmldom/xmldom';
+/** The SOAP version an envelope is written in. */
+export type SoapEnvelopeVersion = '1.1' | '1.2';
+/** The prefix every generated envelope binds its SOAP envelope namespace to. */
+export declare const SOAP_ENVELOPE_PREFIX = "soapenv";
+/** The pieces {@link createEnvelope} wraps. */
+export interface EnvelopeParts {
+    /** Already-rendered header block children; omitted or empty yields `<soapenv:Header/>`. */
+    readonly headerXml?: string;
+    /** Already-rendered body children; empty yields `<soapenv:Body/>`. */
+    readonly bodyXml: string;
+    /** Extra prefix → namespace URI declarations to hoist onto the `Envelope` element. */
+    readonly namespaces?: Readonly<Record<string, string>>;
+}
+/** The SOAP envelope namespace URI for `version`. */
+export declare function envelopeNamespace(version: SoapEnvelopeVersion): string;
+/**
+ * The SOAP version of a parsed document, from its root element's namespace, or
+ * `undefined` when the root is not a SOAP `Envelope`.
+ */
+export declare function detectEnvelopeVersion(doc: Document): SoapEnvelopeVersion | undefined;
+/**
+ * Wraps `parts` in a SOAP envelope.
+ *
+ * The `Header` element is always emitted (empty when there are no header
+ * blocks): it gives the user somewhere to paste a security
+ * header without re-typing the element. Every namespace in
+ * {@link EnvelopeParts.namespaces} is declared on the `Envelope` root, so the
+ * fragments inside carry no `xmlns` declarations of their own.
+ *
+ * Deterministic: identical inputs always produce byte-identical output.
+ *
+ * @param version which SOAP envelope namespace to bind
+ * @param parts the header/body fragments and the namespaces they use
+ * @param options `indent` defaults to three spaces
+ */
+export declare function createEnvelope(version: SoapEnvelopeVersion, parts: EnvelopeParts, options?: {
+    readonly indent?: string;
+}): string;