@wirebench/engine 2.1.1

package/dist/validate/soap-structure.js

@@ -0,0 +1,255 @@
+/**
+ * SOAP envelope structure checks — everything the XSD schema set cannot say
+ * about a message, because the envelope itself is never validated against it:
+ * the envelope namespace (and therefore the SOAP version), the
+ * `Header`/`Body` shape, the `Fault` shape, `mustUnderstand` values, and the
+ * agreement between the transport metadata (`Content-Type`, `SOAPAction`) and
+ * the version in the envelope.
+ *
+ * Tolerant by design: a document that is not well formed yields exactly one
+ * `xml-not-well-formed` problem (with the parser's position) instead of
+ * throwing, so a half-typed envelope still produces a usable marker.
+ */
+import { WirebenchError } from '../errors.js';
+import { NS } from '../xml/namespaces.js';
+import { parseXml, getPosition } from '../xml/parse.js';
+/** The envelope namespace URI for each SOAP version. */
+const ENVELOPE_NS = {
+    '1.1': NS.SOAP11_ENV,
+    '1.2': NS.SOAP12_ENV,
+};
+/** The `Content-Type` media type each SOAP version prescribes. */
+const MEDIA_TYPE = {
+    '1.1': 'text/xml',
+    '1.2': 'application/soap+xml',
+};
+/** Legal `mustUnderstand` values per version: 1.1 allows only `0`/`1`, 1.2 takes any `xs:boolean`. */
+const MUST_UNDERSTAND_VALUES = {
+    '1.1': ['0', '1'],
+    '1.2': ['0', '1', 'true', 'false'],
+};
+/** Builds a problem, folding in the source position of `element` when it has one. */
+function at(element, problem) {
+    const position = element === undefined ? undefined : getPosition(element);
+    return {
+        ...problem,
+        source: 'structure',
+        ...(position !== undefined ? { line: position.line, column: position.column } : {}),
+    };
+}
+/** The direct child elements of `parent`, in document order. */
+function elementChildren(parent) {
+    const result = [];
+    let child = parent.firstChild;
+    while (child !== null) {
+        if (child.nodeType === 1) {
+            result.push(child);
+        }
+        child = child.nextSibling;
+    }
+    return result;
+}
+/** True when `element` has a child element with `localName` in `namespaceUri` that is not empty. */
+function hasChild(element, namespaceUri, localName) {
+    return elementChildren(element).some((child) => child.localName === localName && (namespaceUri === undefined || child.namespaceURI === namespaceUri));
+}
+/** The `Fault` checks for one version; the shapes differ enough that they share nothing but the name. */
+function checkFault(fault, version, problems) {
+    if (version === '1.1') {
+        // SOAP 1.1 Fault children are unqualified.
+        if (!hasChild(fault, undefined, 'faultcode')) {
+            problems.push(at(fault, { severity: 'error', code: 'fault-missing-faultcode', message: 'SOAP 1.1 Fault has no <faultcode>' }));
+        }
+        if (!hasChild(fault, undefined, 'faultstring')) {
+            problems.push(at(fault, {
+                severity: 'error',
+                code: 'fault-missing-faultstring',
+                message: 'SOAP 1.1 Fault has no <faultstring>',
+            }));
+        }
+        return;
+    }
+    const code = elementChildren(fault).find((child) => child.localName === 'Code');
+    if (code === undefined || !hasChild(code, NS.SOAP12_ENV, 'Value')) {
+        problems.push(at(fault, { severity: 'error', code: 'fault-missing-code', message: 'SOAP 1.2 Fault has no <Code><Value>' }));
+    }
+    const reason = elementChildren(fault).find((child) => child.localName === 'Reason');
+    if (reason === undefined || !hasChild(reason, NS.SOAP12_ENV, 'Text')) {
+        problems.push(at(fault, { severity: 'error', code: 'fault-missing-reason', message: 'SOAP 1.2 Fault has no <Reason><Text>' }));
+    }
+}
+/** Checks every header block's `mustUnderstand` attribute against the version's legal values. */
+function checkMustUnderstand(header, version, problems) {
+    const legal = MUST_UNDERSTAND_VALUES[version];
+    for (const block of elementChildren(header)) {
+        const value = block.getAttributeNS(ENVELOPE_NS[version], 'mustUnderstand');
+        if (value === null || value === '' || legal.includes(value)) {
+            continue;
+        }
+        problems.push(at(block, {
+            severity: 'error',
+            code: 'invalid-must-understand',
+            message: `mustUnderstand="${value}" is not legal in SOAP ${version} (expected ${legal.join(' or ')})`,
+        }));
+    }
+}
+/** The value of one `Content-Type` parameter (e.g. `action`), unquoted, or `undefined`. */
+function contentTypeParameter(contentType, name) {
+    const match = new RegExp(`;\\s*${name}\\s*=\\s*("([^"]*)"|[^;\\s]+)`, 'i').exec(contentType);
+    if (match === null) {
+        return undefined;
+    }
+    return match[2] ?? match[1];
+}
+/** Strips the quotes SOAP 1.1 wraps a `SOAPAction` in, so the two spellings compare equal. */
+function unquote(value) {
+    return value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+}
+/** Whether `mediaType` is the media type SOAP `version` sends over the wire, MTOM included:
+ * an MTOM-wrapped message's own `Content-Type` is `multipart/related`, with the actual SOAP
+ * media type carried in its `type` parameter instead. */
+function matchesMediaType(contentType, mediaType, version) {
+    if (mediaType === MEDIA_TYPE[version]) {
+        return true;
+    }
+    if (mediaType !== 'multipart/related') {
+        return false;
+    }
+    const type = contentTypeParameter(contentType, 'type');
+    return type !== undefined && unquote(type).toLowerCase() === MEDIA_TYPE[version];
+}
+/**
+ * Compares the transport metadata against the version in the envelope. Media-type and
+ * `action`-parameter mismatches are independent findings — a message can carry both — so
+ * neither check short-circuits the other.
+ */
+function checkTransport(options, problems) {
+    const { contentType, expectedVersion, soapAction } = options;
+    if (contentType === undefined) {
+        return;
+    }
+    const mediaType = (contentType.split(';')[0] ?? '').trim().toLowerCase();
+    if (mediaType.length > 0 && !matchesMediaType(contentType, mediaType, expectedVersion)) {
+        problems.push({
+            severity: 'warning',
+            code: 'content-type-mismatch',
+            message: `SOAP ${expectedVersion} expects Content-Type ${MEDIA_TYPE[expectedVersion]}, not ${mediaType}`,
+            source: 'structure',
+        });
+    }
+    if (expectedVersion !== '1.2' || soapAction === undefined) {
+        return;
+    }
+    const action = contentTypeParameter(contentType, 'action');
+    if (action !== undefined && unquote(action) !== unquote(soapAction)) {
+        problems.push({
+            severity: 'warning',
+            code: 'soap-action-mismatch',
+            message: `Content-Type action="${unquote(action)}" does not match the operation's action "${unquote(soapAction)}"`,
+            source: 'structure',
+        });
+    }
+}
+/**
+ * Checks the SOAP-level structure of `xml` against the binding's expectations.
+ *
+ * Never throws: a parse failure is reported as a single `xml-not-well-formed`
+ * problem carrying the parser's line/column.
+ *
+ * @param xml the whole envelope text, as typed in the editor
+ * @param options the binding's SOAP version, plus the transport metadata to cross-check
+ * @returns every finding, in document order (transport findings last)
+ */
+export function checkSoapStructure(xml, options) {
+    const problems = [];
+    let root;
+    try {
+        root = parseXml(xml).documentElement;
+    }
+    catch (cause) {
+        const details = cause instanceof WirebenchError ? cause.details : undefined;
+        const line = typeof details?.['line'] === 'number' ? details['line'] : undefined;
+        const column = typeof details?.['column'] === 'number' ? details['column'] : undefined;
+        return [
+            {
+                severity: 'error',
+                code: 'xml-not-well-formed',
+                message: cause instanceof Error ? cause.message : 'The message is not well-formed XML',
+                source: 'structure',
+                ...(line !== undefined ? { line } : {}),
+                ...(column !== undefined ? { column } : {}),
+            },
+        ];
+    }
+    if (root === null) {
+        return [
+            {
+                severity: 'error',
+                code: 'xml-not-well-formed',
+                message: 'The message is empty or has no root element',
+                source: 'structure',
+            },
+        ];
+    }
+    const version = root.namespaceURI === NS.SOAP11_ENV ? '1.1' : root.namespaceURI === NS.SOAP12_ENV ? '1.2' : undefined;
+    if (root.localName !== 'Envelope' || version === undefined) {
+        problems.push(at(root, {
+            severity: 'error',
+            code: 'not-an-envelope',
+            message: `Expected a SOAP ${options.expectedVersion} <Envelope>, found <${root.tagName}>`,
+            path: `/${root.tagName}`,
+        }));
+        return problems;
+    }
+    if (version !== options.expectedVersion) {
+        problems.push(at(root, {
+            severity: 'error',
+            code: 'soap-version-mismatch',
+            message: `The binding is SOAP ${options.expectedVersion} but this envelope is SOAP ${version}`,
+            path: `/${root.tagName}`,
+        }));
+    }
+    const envelopeNs = ENVELOPE_NS[version];
+    const children = elementChildren(root);
+    const headers = children.filter((child) => child.namespaceURI === envelopeNs && child.localName === 'Header');
+    const bodies = children.filter((child) => child.namespaceURI === envelopeNs && child.localName === 'Body');
+    for (const child of children) {
+        if (child.namespaceURI === envelopeNs && (child.localName === 'Header' || child.localName === 'Body')) {
+            continue;
+        }
+        problems.push(at(child, {
+            severity: 'error',
+            code: 'unexpected-envelope-child',
+            message: `<${child.tagName}> is not allowed as a direct child of <Envelope>`,
+        }));
+    }
+    if (headers.length > 1) {
+        problems.push(at(headers[1], {
+            severity: 'error',
+            code: 'multiple-header',
+            message: 'An envelope may carry only one <Header>',
+        }));
+    }
+    else if (headers.length === 1 &&
+        bodies.length > 0 &&
+        children.indexOf(headers[0]) > children.indexOf(bodies[0])) {
+        problems.push(at(headers[0], { severity: 'error', code: 'header-after-body', message: '<Header> must precede <Body>' }));
+    }
+    if (bodies.length === 0) {
+        problems.push(at(root, { severity: 'error', code: 'missing-body', message: 'The envelope has no <Body>' }));
+    }
+    else if (bodies.length > 1) {
+        problems.push(at(bodies[1], { severity: 'error', code: 'multiple-body', message: 'An envelope may carry only one <Body>' }));
+    }
+    const header = headers[0];
+    if (header !== undefined) {
+        checkMustUnderstand(header, version, problems);
+    }
+    const body = bodies[0];
+    const fault = body === undefined ? undefined : elementChildren(body).find((child) => child.localName === 'Fault');
+    if (fault !== undefined && fault.namespaceURI === envelopeNs) {
+        checkFault(fault, version, problems);
+    }
+    checkTransport(options, problems);
+    return problems;
+}

package/dist/validate/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The problem shape every message validator reports, shared by the XSD schema
+ * validator (`schema-validator.ts`) and the SOAP structure checks
+ * (`soap-structure.ts`). Positions are 1-based and refer to the *envelope*
+ * text that was validated, so a UI can turn one straight into an editor
+ * marker.
+ */
+/** How badly a validation finding matters. */
+export type ValidationSeverity = 'error' | 'warning';
+/** Which validator raised a finding: the XSD validator, the SOAP structure checks, or WS-I. */
+export type ValidationSource = 'schema' | 'structure' | 'ws-i';
+/** One finding about a SOAP message. */
+export interface ValidationProblem {
+    readonly severity: ValidationSeverity;
+    /** Stable, machine-readable code (e.g. `soap-version-mismatch`, `schema-invalid`). */
+    readonly code: string;
+    readonly message: string;
+    /** 1-based line in the validated envelope text. */
+    readonly line?: number;
+    /** 1-based column in the validated envelope text. */
+    readonly column?: number;
+    readonly endLine?: number;
+    readonly endColumn?: number;
+    readonly source: ValidationSource;
+    /** A human-readable element path (e.g. `/Envelope/Body/Add`), when one is known. */
+    readonly path?: string;
+}
+/** One `wsdl:part` as the validator needs it: a name plus the element or type it carries. */
+export interface ValidationPart {
+    readonly name: string;
+    readonly element?: {
+        readonly namespaceUri: string;
+        readonly localName: string;
+    };
+    readonly type?: {
+        readonly namespaceUri: string;
+        readonly localName: string;
+    };
+}
+/** The binding context one message is validated in. */
+export interface ValidationBinding {
+    readonly soapVersion: '1.1' | '1.2';
+    readonly operation: string;
+    readonly style: 'document' | 'rpc';
+    /** The parts of the message being validated (input for a request, output for a response). */
+    readonly parts: readonly ValidationPart[];
+}

package/dist/validate/types.js

@@ -0,0 +1,8 @@
+/**
+ * The problem shape every message validator reports, shared by the XSD schema
+ * validator (`schema-validator.ts`) and the SOAP structure checks
+ * (`soap-structure.ts`). Positions are 1-based and refer to the *envelope*
+ * text that was validated, so a UI can turn one straight into an editor
+ * marker.
+ */
+export {};

package/dist/validate/wsi/assertions/helpers.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Shared DOM navigation for the WS-I assertions.
+ *
+ * The assertions work on the *raw* documents rather than the merged {@link WsdlDefinition}: the
+ * profile constrains constructs the model normalizes away (a missing `use` attribute, a `parts`
+ * list, the order of `wsdl:input`/`wsdl:output`), and findings need the document and position the
+ * offending element actually came from.
+ */
+import type { Element } from '@xmldom/xmldom';
+import type { QName } from '../../../wsdl/qname.js';
+import type { BundledDocument } from '../../../wsdl/resolver.js';
+import type { WsiFinding, WsiWsdlContext } from '../types.js';
+/** The two WSDL SOAP binding namespaces, in the order they are probed. */
+export declare const SOAP_BINDING_NAMESPACES: readonly ["http://schemas.xmlsoap.org/wsdl/soap/", "http://schemas.xmlsoap.org/wsdl/soap12/"];
+/** One `wsdl:definitions` document of the bundle. */
+export interface WsdlDocumentView {
+    readonly location: string;
+    readonly definitions: Element;
+}
+/** Every `wsdl:definitions` document in the bundle, in discovery order. */
+export declare function wsdlDocuments(context: WsiWsdlContext): readonly WsdlDocumentView[];
+/** One `xs:schema` element of the bundle, with the document it was found in. */
+export interface SchemaView {
+    readonly location: string;
+    readonly schema: Element;
+}
+/** Every `xs:schema` element in the bundle: the inline ones first, then standalone XSD roots. */
+export declare function schemaElements(context: WsiWsdlContext): readonly SchemaView[];
+/** Every descendant element of `root` (excluding `root` itself), depth first. */
+export declare function descendants(root: Element): readonly Element[];
+/** The SOAP binding namespace a `wsdl:binding` uses, or `undefined` when it is not a SOAP binding. */
+export declare function soapNamespaceOf(binding: Element): string | undefined;
+/** The SOAP bindings of every document, paired with the SOAP namespace they use. */
+export interface SoapBindingView {
+    readonly location: string;
+    readonly binding: Element;
+    readonly soapNs: string;
+    /** The binding's `soapbind:binding` element. */
+    readonly soapBinding: Element;
+}
+/** Every `wsdl:binding` that is a SOAP binding, across the whole bundle. */
+export declare function soapBindings(context: WsiWsdlContext): readonly SoapBindingView[];
+/** The effective style of one binding operation: its own `soapbind:operation/@style`, else the binding's. */
+export declare function operationStyle(view: SoapBindingView, operation: Element): 'document' | 'rpc';
+/** The `wsdl:input`/`wsdl:output` children of a binding operation, in document order. */
+export declare function bindingMessages(operation: Element): readonly Element[];
+/** The `soapbind:body` of a binding `wsdl:input`/`wsdl:output`, if it declares one. */
+export declare function soapBodyOf(message: Element, soapNs: string): Element | undefined;
+/** Resolves a QName-valued attribute against the in-scope prefixes of `element`. */
+export declare function attributeQName(element: Element, attribute: string, defaultNamespace: string): QName | undefined;
+/** The `targetNamespace` of the `wsdl:definitions` an element belongs to (empty string when absent). */
+export declare function targetNamespaceOf(definitions: Element): string;
+/**
+ * Every namespace the description defines or imports: the `targetNamespace` of each
+ * `wsdl:definitions` and each `xs:schema` of the bundle, the `namespace` of each
+ * `wsdl:import`/`xs:import`, and the XML Schema namespace itself (always available to a
+ * description). This is the set R2101 and R2102 measure their QName references against.
+ */
+export declare function declaredNamespaces(context: WsiWsdlContext): ReadonlySet<string>;
+/** A bundle-wide index of the WSDL components assertions cross-reference, keyed by Clark name. */
+export interface WsdlIndex {
+    readonly messages: ReadonlyMap<string, WsdlComponent>;
+    readonly portTypes: ReadonlyMap<string, WsdlComponent>;
+}
+/** One indexed WSDL component: its element plus the document it came from. */
+export interface WsdlComponent {
+    readonly location: string;
+    readonly element: Element;
+}
+/** Indexes every `wsdl:message` and `wsdl:portType` of the bundle by expanded name (cached per context). */
+export declare function wsdlIndex(context: WsiWsdlContext): WsdlIndex;
+/** Looks a `wsdl:message` up by the QName an attribute of `element` refers to. */
+export declare function referencedMessage(context: WsiWsdlContext, element: Element, attribute: string, defaultNamespace: string): WsdlComponent | undefined;
+/** The `wsdl:part` children of a `wsdl:message`. */
+export declare function messageParts(message: Element): readonly Element[];
+/** Finds a `wsdl:part` of `message` by name. */
+export declare function findPart(message: Element, name: string): Element | undefined;
+/** A readable element path, using `@name` where an element has one and a position index otherwise. */
+export declare function xpathOf(element: Element): string;
+/** Builds a finding pointing at `element` in the document at `location`. */
+export declare function findingAt(location: string, element: Element, message: string): WsiFinding;
+/** True when `value` is an absolute URI (a scheme followed by a scheme-specific part). */
+export declare function isAbsoluteUri(value: string): boolean;
+/** Resolves a relative reference against a base location, returning `undefined` when it is not resolvable. */
+export declare function resolveAgainst(reference: string, base: string): string | undefined;
+/** Looks a bundled document up by the location one of its importers referenced. */
+export declare function bundledDocumentFor(context: WsiWsdlContext, resolvedLocation: string): BundledDocument | undefined;
+/** One side of one binding operation, joined to the abstract message it binds. */
+export interface BoundMessageView {
+    readonly location: string;
+    readonly bindingView: SoapBindingView;
+    /** The `wsdl:operation` inside the `wsdl:binding`. */
+    readonly operation: Element;
+    readonly direction: 'input' | 'output' | 'fault';
+    /** The `wsdl:input`/`wsdl:output`/`wsdl:fault` inside the binding operation. */
+    readonly messageElement: Element;
+    readonly soapBody?: Element;
+    readonly style: 'document' | 'rpc';
+    /** The `wsdl:message` the port type's operation refers to, when it resolves. */
+    readonly abstractMessage?: WsdlComponent;
+    /** Every `wsdl:part` of that message. */
+    readonly parts: readonly Element[];
+    /** The names listed in `soapbind:body/@parts`, or `undefined` when the attribute is absent. */
+    readonly declaredParts?: readonly string[];
+    /**
+     * The parts actually bound to the SOAP body: the declared subset, or all of them. Always empty
+     * for a `fault` view — a fault's part is bound by `soapbind:fault`, never by `soapbind:body`.
+     */
+    readonly boundParts: readonly Element[];
+    /**
+     * The parts bound to *any* SOAP construct: the body-bound ones plus every part this binding
+     * operation's `soapbind:header`/`headerfault` elements name on the same abstract message. For a
+     * `fault` view it is every part of the fault message when the `wsdl:fault` carries a
+     * `soapbind:fault`, and nothing otherwise: a fault message has a single, implicitly bound part,
+     * so the binding either declares the fault or leaves it unbound.
+     */
+    readonly soapBoundParts: readonly Element[];
+}
+/** The `wsdl:portType` a binding refers to, when it resolves. */
+export declare function portTypeOf(context: WsiWsdlContext, view: SoapBindingView, definitions: Element): WsdlComponent | undefined;
+/** Joins every binding operation's input/output to the abstract message it binds. */
+export declare function boundMessages(context: WsiWsdlContext): readonly BoundMessageView[];
+/** One `soapbind:` extension element of a binding, with the context needed to judge it. */
+export interface SoapExtensionView {
+    readonly location: string;
+    readonly bindingView: SoapBindingView;
+    /** The `wsdl:operation` of the binding the extension belongs to. */
+    readonly operation: Element;
+    /** The `soapbind:body`/`header`/`headerfault`/`fault` element itself. */
+    readonly element: Element;
+    readonly kind: 'body' | 'header' | 'headerfault' | 'fault';
+    /** The enclosing `wsdl:fault`, for a `soapbind:fault`. */
+    readonly wsdlFault?: Element;
+    readonly style: 'document' | 'rpc';
+}
+/** Every `soapbind:body`/`header`/`headerfault`/`fault` element of every SOAP binding. */
+export declare function soapExtensions(context: WsiWsdlContext): readonly SoapExtensionView[];
+/** One `soapbind:address` of a `wsdl:port`. */
+export interface SoapAddressView {
+    readonly location: string;
+    readonly port: Element;
+    readonly address: Element;
+}
+/** Every `soapbind:address` element in the bundle. */
+export declare function soapAddresses(context: WsiWsdlContext): readonly SoapAddressView[];