@wirebench/engine 2.1.1

package/dist/wsdl/parse-wsdl.js

@@ -0,0 +1,161 @@
+import { WsdlParseError } from '../errors.js';
+import { NS } from '../xml/namespaces.js';
+import { getPosition, parseXml } from '../xml/parse.js';
+import { childElements, firstChildElement, optionalAttribute, readDocumentation, requireAttribute, } from './dom-utils.js';
+import { parseWsdlBundle } from './merge.js';
+import { parseBinding, parseService } from './parse-binding.js';
+import { parseQName } from './qname.js';
+import { resolveDefinition } from './resolver.js';
+function parsePart(partEl, location, defaultNamespace) {
+    const elementAttr = optionalAttribute(partEl, 'element');
+    const typeAttr = optionalAttribute(partEl, 'type');
+    return {
+        name: requireAttribute(partEl, 'name', location),
+        ...(elementAttr !== undefined ? { element: parseQName(elementAttr, partEl, defaultNamespace) } : {}),
+        ...(typeAttr !== undefined ? { type: parseQName(typeAttr, partEl, defaultNamespace) } : {}),
+    };
+}
+function parseMessage(messageEl, location, defaultNamespace) {
+    const documentation = readDocumentation(messageEl, NS.WSDL);
+    const parts = childElements(messageEl, NS.WSDL, 'part').map((p) => parsePart(p, location, defaultNamespace));
+    const name = { namespaceUri: defaultNamespace, localName: requireAttribute(messageEl, 'name', location) };
+    return {
+        name,
+        ...(documentation !== undefined ? { documentation } : {}),
+        parts,
+    };
+}
+function parseMessageRef(el, location, defaultNamespace) {
+    const name = optionalAttribute(el, 'name');
+    return {
+        ...(name !== undefined ? { name } : {}),
+        message: parseQName(requireAttribute(el, 'message', location), el, defaultNamespace),
+        sourceElement: el,
+    };
+}
+function parseOperationFault(el, location, defaultNamespace) {
+    const documentation = readDocumentation(el, NS.WSDL);
+    return {
+        name: requireAttribute(el, 'name', location),
+        message: parseQName(requireAttribute(el, 'message', location), el, defaultNamespace),
+        ...(documentation !== undefined ? { documentation } : {}),
+    };
+}
+function parseOperation(opEl, location, defaultNamespace) {
+    const documentation = readDocumentation(opEl, NS.WSDL);
+    const inputEl = firstChildElement(opEl, NS.WSDL, 'input');
+    const outputEl = firstChildElement(opEl, NS.WSDL, 'output');
+    const faults = childElements(opEl, NS.WSDL, 'fault').map((f) => parseOperationFault(f, location, defaultNamespace));
+    const parameterOrderAttr = optionalAttribute(opEl, 'parameterOrder');
+    return {
+        name: requireAttribute(opEl, 'name', location),
+        ...(documentation !== undefined ? { documentation } : {}),
+        ...(inputEl !== undefined ? { input: parseMessageRef(inputEl, location, defaultNamespace) } : {}),
+        ...(outputEl !== undefined ? { output: parseMessageRef(outputEl, location, defaultNamespace) } : {}),
+        faults,
+        ...(parameterOrderAttr !== undefined
+            ? { parameterOrder: parameterOrderAttr.split(/\s+/).filter((p) => p.length > 0) }
+            : {}),
+    };
+}
+function parsePortType(portTypeEl, location, defaultNamespace) {
+    const documentation = readDocumentation(portTypeEl, NS.WSDL);
+    const operations = childElements(portTypeEl, NS.WSDL, 'operation').map((op) => parseOperation(op, location, defaultNamespace));
+    const name = { namespaceUri: defaultNamespace, localName: requireAttribute(portTypeEl, 'name', location) };
+    return {
+        name,
+        ...(documentation !== undefined ? { documentation } : {}),
+        operations,
+    };
+}
+function parseImport(importEl, location) {
+    const namespace = optionalAttribute(importEl, 'namespace');
+    return {
+        ...(namespace !== undefined ? { namespace } : {}),
+        location: requireAttribute(importEl, 'location', location),
+    };
+}
+/**
+ * Collects the `xmlns:*` declarations on the root `wsdl:definitions` element.
+ * The default (unprefixed) `xmlns` declaration is deliberately excluded: the
+ * values these are used to resolve (`wsdl:arrayType`) are always prefixed.
+ */
+function readNamespaceDeclarations(root) {
+    const declarations = {};
+    const attributes = root.attributes;
+    for (let i = 0; i < attributes.length; i += 1) {
+        const attribute = attributes.item(i);
+        if (attribute !== null && attribute.name.startsWith('xmlns:')) {
+            declarations[attribute.name.slice('xmlns:'.length)] = attribute.value;
+        }
+    }
+    return declarations;
+}
+/**
+ * Parses a single, already-loaded WSDL 1.1 `Document` into a {@link WsdlDefinition}.
+ *
+ * Pure and synchronous: it does not resolve `wsdl:import`s or fetch anything,
+ * and does not validate cross-references (e.g. a binding's `type` pointing at
+ * an unknown `portType`) — only structural requirements of the WSDL document
+ * itself (required attributes) are enforced.
+ *
+ * @param doc the parsed WSDL document
+ * @param location a human-readable origin for the document, echoed into the resulting model and errors
+ * @throws {WsdlParseError} with code `not-a-wsdl` if the root element is not `{NS.WSDL}definitions`
+ * @throws {WsdlParseError} with code `wsdl-invalid` for structural errors (e.g. a missing required attribute)
+ */
+export function parseWsdlDocument(doc, location) {
+    const root = doc.documentElement;
+    if (root === null || root.namespaceURI !== NS.WSDL || root.localName !== 'definitions') {
+        const pos = root !== null ? getPosition(root) : undefined;
+        throw new WsdlParseError('not-a-wsdl', `Document at "${location}" is not a WSDL 1.1 <definitions> root`, {
+            details: { location, rootTag: root?.tagName, ...pos },
+        });
+    }
+    const targetNamespace = optionalAttribute(root, 'targetNamespace') ?? '';
+    const namespaceDeclarations = readNamespaceDeclarations(root);
+    const documentation = readDocumentation(root, NS.WSDL);
+    const typesEl = firstChildElement(root, NS.WSDL, 'types');
+    const schemaElements = typesEl !== undefined ? childElements(typesEl, NS.XSD, 'schema') : [];
+    const imports = childElements(root, NS.WSDL, 'import').map((el) => parseImport(el, location));
+    const messages = childElements(root, NS.WSDL, 'message').map((el) => parseMessage(el, location, targetNamespace));
+    const portTypes = childElements(root, NS.WSDL, 'portType').map((el) => parsePortType(el, location, targetNamespace));
+    const bindings = childElements(root, NS.WSDL, 'binding').map((el) => parseBinding(el, location, targetNamespace));
+    const services = childElements(root, NS.WSDL, 'service').map((el) => parseService(el, location, targetNamespace));
+    return {
+        location,
+        targetNamespace,
+        ...(documentation !== undefined ? { documentation } : {}),
+        messages,
+        portTypes,
+        bindings,
+        services,
+        schemaElements,
+        imports,
+        namespaceDeclarations,
+        problems: [],
+    };
+}
+/**
+ * Parses a WSDL 1.1 document, given its root source.
+ *
+ * When `options.resolveImports` is `false`, only `root.text` is parsed as a
+ * single document (`fetchDocument` is unused). When `true`, the full import
+ * graph (`wsdl:import`/`xsd:import`/`xsd:include`/`xsd:redefine`) is resolved
+ * via {@link resolveDefinition} and merged via {@link parseWsdlBundle}.
+ *
+ * @throws {WsdlParseError} propagated from {@link parseWsdlDocument} for `not-a-wsdl`/`wsdl-invalid`
+ * @throws {WsdlParseError} with code `fetch-failed` if the root document cannot be fetched while resolving imports
+ */
+export async function parseWsdl(root, options) {
+    if (!options.resolveImports) {
+        if (root.text === undefined) {
+            throw new WsdlParseError('wsdl-invalid', 'root.text is required when resolveImports is false', {
+                details: { location: root.location },
+            });
+        }
+        return parseWsdlDocument(parseXml(root.text, { location: root.location }), root.location);
+    }
+    const bundle = await resolveDefinition({ location: root.location, ...(root.text !== undefined ? { text: root.text } : {}) }, { fetchDocument: options.fetchDocument, ...(options.signal !== undefined ? { signal: options.signal } : {}) });
+    return parseWsdlBundle(bundle);
+}

package/dist/wsdl/qname.d.ts

@@ -0,0 +1,28 @@
+import type { Element } from '@xmldom/xmldom';
+/** A namespace-qualified name: an expanded `{namespaceUri}localName` pair. */
+export interface QName {
+    readonly namespaceUri: string;
+    readonly localName: string;
+}
+/**
+ * Resolves a (possibly prefixed) QName string against the namespaces in
+ * scope at `contextElement`, walking ancestors via `lookupNamespaceURI`.
+ *
+ * An unprefixed name resolves, in order: (1) to the in-scope XML default
+ * namespace (an `xmlns="…"` declared on `contextElement` or an ancestor),
+ * when one is declared; (2) otherwise to `defaultNamespace`, when given
+ * (callers pass the enclosing `wsdl:definitions` `targetNamespace` for WSDL
+ * references, mirroring wsdl4j's lenient fallback for documents that omit a
+ * default namespace declaration). This applies uniformly to every
+ * QName-valued attribute (`message`, `binding`, `type`, `element`, part refs).
+ *
+ * @param prefixed the raw attribute value, e.g. `"tns:Add"` or `"Add"`
+ * @param contextElement the element the value was read from, used to resolve prefixes in scope
+ * @param defaultNamespace fallback namespace when `prefixed` carries no prefix and no default namespace is declared in scope
+ * @throws {Error} if a prefix is present but not bound in scope
+ */
+export declare function parseQName(prefixed: string, contextElement: Element, defaultNamespace?: string): QName;
+/** True when two QNames refer to the same expanded name. */
+export declare function qnameEquals(a: QName, b: QName): boolean;
+/** Renders a QName in Clark notation: `{namespaceUri}localName`. */
+export declare function qnameToString(qname: QName): string;

package/dist/wsdl/qname.js

@@ -0,0 +1,41 @@
+/**
+ * Resolves a (possibly prefixed) QName string against the namespaces in
+ * scope at `contextElement`, walking ancestors via `lookupNamespaceURI`.
+ *
+ * An unprefixed name resolves, in order: (1) to the in-scope XML default
+ * namespace (an `xmlns="…"` declared on `contextElement` or an ancestor),
+ * when one is declared; (2) otherwise to `defaultNamespace`, when given
+ * (callers pass the enclosing `wsdl:definitions` `targetNamespace` for WSDL
+ * references, mirroring wsdl4j's lenient fallback for documents that omit a
+ * default namespace declaration). This applies uniformly to every
+ * QName-valued attribute (`message`, `binding`, `type`, `element`, part refs).
+ *
+ * @param prefixed the raw attribute value, e.g. `"tns:Add"` or `"Add"`
+ * @param contextElement the element the value was read from, used to resolve prefixes in scope
+ * @param defaultNamespace fallback namespace when `prefixed` carries no prefix and no default namespace is declared in scope
+ * @throws {Error} if a prefix is present but not bound in scope
+ */
+export function parseQName(prefixed, contextElement, defaultNamespace) {
+    const trimmed = prefixed.trim();
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) {
+        const declaredDefault = contextElement.lookupNamespaceURI('');
+        const namespaceUri = declaredDefault ?? defaultNamespace ?? '';
+        return { namespaceUri, localName: trimmed };
+    }
+    const prefix = trimmed.slice(0, colonIndex);
+    const localName = trimmed.slice(colonIndex + 1);
+    const namespaceUri = contextElement.lookupNamespaceURI(prefix);
+    if (namespaceUri === null) {
+        throw new Error(`Unbound namespace prefix "${prefix}" in QName "${prefixed}"`);
+    }
+    return { namespaceUri, localName };
+}
+/** True when two QNames refer to the same expanded name. */
+export function qnameEquals(a, b) {
+    return a.namespaceUri === b.namespaceUri && a.localName === b.localName;
+}
+/** Renders a QName in Clark notation: `{namespaceUri}localName`. */
+export function qnameToString(qname) {
+    return `{${qname.namespaceUri}}${qname.localName}`;
+}

package/dist/wsdl/ref-policy.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What a WSDL/XSD document is allowed to reference.
+ *
+ * Importing a definition means fetching whatever it points at, transitively. Without a policy
+ * that is a file-read primitive handed to whoever wrote the WSDL: a remote document whose
+ * `xs:import schemaLocation="file:///etc/hosts"` is followed would exfiltrate a local file
+ * into the import bundle, which the UI then happily displays. The rule below is deliberately
+ * blunt — a nested reference stays in the same world as the root document — because anything
+ * subtler is a rule nobody can hold in their head while reading a WSDL.
+ */
+/** How deep an import chain may go before the graph is treated as runaway. */
+export declare const MAX_IMPORT_DEPTH = 32;
+/** How many documents one definition may pull in before the graph is treated as runaway. */
+export declare const MAX_IMPORT_DOCUMENTS = 500;
+/**
+ * Classifies an absolute location by the world it lives in: `'file'`, `'http'` (covering
+ * `https`, so an `http` root may reference an `https` document and vice versa), or the
+ * location's own scheme for anything else (`mem`, `inline`, `dropped`, …).
+ *
+ * @param location the absolute location to classify
+ * @returns the lower-cased scheme, with `https` folded into `http`
+ */
+export declare function classifyLocation(location: string): string;
+/** A refused reference, with the sentence shown to the user. */
+export interface RefusedReference {
+    readonly reason: string;
+}
+/**
+ * The policy a single import graph is resolved under, derived from its root document.
+ *
+ * - A `file:` root may reference `file:` documents only, and only inside its own directory
+ *   tree (real paths, so a planted symlink cannot walk out).
+ * - An `http(s):` root may reference any `http(s):` host, and never `file:`. Reaching an
+ *   internal host that way is inherent to importing a remote WSDL — the user asked for that
+ *   document, and the document says where its schemas live — so it is documented rather than
+ *   blocked.
+ * - Any other root (a pasted `inline:` or dropped `dropped:` document, a test `mem:` one) may
+ *   reference its own scheme or `http(s):`, and never `file:`: it has no directory of its own,
+ *   so there is no tree a local reference could be confined to.
+ */
+export interface ReferencePolicy {
+    /**
+     * Whether `reference` may be fetched, and why not when it may not.
+     *
+     * @param reference the absolute location the referring document resolved to
+     */
+    allows(reference: string): Promise<RefusedReference | undefined>;
+}
+/**
+ * Builds the {@link ReferencePolicy} for a graph rooted at `rootLocation`.
+ *
+ * @param rootLocation the root document's absolute location (post-redirect)
+ */
+export declare function referencePolicyFor(rootLocation: string): ReferencePolicy;

package/dist/wsdl/ref-policy.js

@@ -0,0 +1,87 @@
+/**
+ * What a WSDL/XSD document is allowed to reference.
+ *
+ * Importing a definition means fetching whatever it points at, transitively. Without a policy
+ * that is a file-read primitive handed to whoever wrote the WSDL: a remote document whose
+ * `xs:import schemaLocation="file:///etc/hosts"` is followed would exfiltrate a local file
+ * into the import bundle, which the UI then happily displays. The rule below is deliberately
+ * blunt — a nested reference stays in the same world as the root document — because anything
+ * subtler is a rule nobody can hold in their head while reading a WSDL.
+ */
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isInsideRealDir } from '../fs.js';
+/** How deep an import chain may go before the graph is treated as runaway. */
+export const MAX_IMPORT_DEPTH = 32;
+/** How many documents one definition may pull in before the graph is treated as runaway. */
+export const MAX_IMPORT_DOCUMENTS = 500;
+/**
+ * Classifies an absolute location by the world it lives in: `'file'`, `'http'` (covering
+ * `https`, so an `http` root may reference an `https` document and vice versa), or the
+ * location's own scheme for anything else (`mem`, `inline`, `dropped`, …).
+ *
+ * @param location the absolute location to classify
+ * @returns the lower-cased scheme, with `https` folded into `http`
+ */
+export function classifyLocation(location) {
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(location)?.[1]?.toLowerCase();
+    if (scheme === undefined) {
+        return 'relative';
+    }
+    return scheme === 'https' ? 'http' : scheme;
+}
+/** The directory of a `file:` URL, or `undefined` when it is not a usable file path here. */
+function toDirOrUndefined(location) {
+    try {
+        return dirname(fileURLToPath(location));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Builds the {@link ReferencePolicy} for a graph rooted at `rootLocation`.
+ *
+ * @param rootLocation the root document's absolute location (post-redirect)
+ */
+export function referencePolicyFor(rootLocation) {
+    const rootClass = classifyLocation(rootLocation);
+    // A `file:` URL that no platform can turn into a path (`file:///x` has no drive letter on
+    // Windows) leaves the graph with no folder to be confined to. That is a refusal, not a
+    // crash: resolving must report a problem, never throw out of the fetcher.
+    const rootDir = rootClass === 'file' ? toDirOrUndefined(rootLocation) : undefined;
+    return {
+        async allows(reference) {
+            const refClass = classifyLocation(reference);
+            if (refClass === 'file') {
+                if (rootDir === undefined) {
+                    return {
+                        reason: rootClass === 'file'
+                            ? "the definition's own location is not a usable file: URL"
+                            : rootClass === 'http'
+                                ? 'a remote definition may not reference local files'
+                                : 'only a definition imported from a file may reference local files',
+                    };
+                }
+                let path;
+                try {
+                    path = fileURLToPath(reference);
+                }
+                catch {
+                    return { reason: 'the reference is not a usable file: URL' };
+                }
+                if (!(await isInsideRealDir(rootDir, path))) {
+                    return { reason: `it resolves outside the definition's folder (${rootDir})` };
+                }
+                return undefined;
+            }
+            if (rootClass === 'file') {
+                return { reason: 'a definition imported from a file may only reference files beside it' };
+            }
+            if (refClass === rootClass || refClass === 'http') {
+                return undefined;
+            }
+            return { reason: `a ${rootClass}: definition may not reference a ${refClass}: document` };
+        },
+    };
+}

package/dist/wsdl/resolver.d.ts

@@ -0,0 +1,81 @@
+import type { Document } from '@xmldom/xmldom';
+/** The root document to resolve, plus an optional pre-fetched body (avoids a redundant fetch of the root). */
+export interface DefinitionSource {
+    /** Absolute URL (`http(s)://` or `file://`) identifying the root document. */
+    readonly location: string;
+    /** Pre-fetched root document text, when the caller already has it in hand. */
+    readonly text?: string;
+}
+/** A fetched document's canonical location (post-redirect) and raw content. */
+export interface FetchedDocument {
+    /** The final absolute location after following any redirects. */
+    readonly location: string;
+    readonly bytes: Uint8Array;
+    readonly text: string;
+}
+/** Fetches a single document by absolute location, honouring an optional abort signal. */
+export type FetchDocument = (location: string, signal?: AbortSignal) => Promise<FetchedDocument>;
+/** Options for {@link resolveDefinition}. */
+export interface ResolveOptions {
+    readonly fetchDocument: FetchDocument;
+    readonly signal?: AbortSignal;
+}
+/** A single document collected while resolving a WSDL/XSD import graph. */
+export interface BundledDocument {
+    /** The document's canonical (post-redirect) absolute location. */
+    readonly location: string;
+    /** The absolute location that was requested to obtain this document, prior to any redirect. */
+    readonly requestedLocation: string;
+    readonly bytes: Uint8Array;
+    readonly text: string;
+    readonly kind: 'wsdl' | 'xsd';
+    /** The location of the document whose `import`/`include`/`redefine` referenced this one, if any (absent for the root). */
+    readonly importedBy?: string;
+    /** This document's `targetNamespace`, or the namespace a chameleon include adopted from its includer. */
+    readonly namespace?: string;
+    /** For a chameleon include (an `xs:include` target with no `targetNamespace` of its own): the including document's location. */
+    readonly chameleonFor?: string;
+    readonly document: Document;
+}
+/** A non-fatal problem encountered while resolving an import graph. */
+export interface ResolveProblem {
+    readonly code: 'unsupported-redefine' | 'fetch-failed' | 'unresolved-import' | 'not-xml'
+    /** A reference the {@link ReferencePolicy} refused; see `wsdl/ref-policy.ts`. */
+     | 'import-ref-refused'
+    /** The graph hit the depth or document cap; everything resolved so far is still returned. */
+     | 'import-limit';
+    readonly message: string;
+    readonly location: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+/** The full set of documents discovered while resolving a WSDL's import graph, plus any problems encountered. */
+export interface DefinitionBundle {
+    readonly root: BundledDocument;
+    /** Root first, then every imported/included/redefined document in discovery order. */
+    readonly documents: readonly BundledDocument[];
+    readonly problems: readonly ResolveProblem[];
+}
+/**
+ * Resolves a WSDL/XSD document's full import graph (`wsdl:import`, `xs:import`,
+ * `xs:include`, `xs:redefine`) into a flat {@link DefinitionBundle}, fetching
+ * every referenced document exactly once (by canonical, post-redirect
+ * location) through the injected `fetchDocument`.
+ *
+ * Every nested reference is first judged against the root document's world (see
+ * `wsdl/ref-policy.ts`): a `file:` root may only reference `file:` documents inside its own
+ * folder, an `http(s):` root may only reference `http(s):` documents, and a pasted/dropped
+ * root may only reference `http(s):` documents. A refused reference becomes an
+ * `import-ref-refused` problem and the import continues with what did resolve — so a WSDL
+ * cannot be used to read arbitrary local files. The graph is additionally capped at
+ * {@link MAX_IMPORT_DEPTH} levels and {@link MAX_IMPORT_DOCUMENTS} documents (`import-limit`).
+ *
+ * A failed fetch of an imported/included document is recorded as a
+ * `fetch-failed` {@link ResolveProblem} and resolution continues with the
+ * rest of the graph; a failed fetch of the root document throws instead,
+ * since there is nothing to return without it.
+ *
+ * @throws {WsdlParseError} with code `fetch-failed` if the root document cannot be fetched
+ * @throws if `options.signal` is already aborted, or becomes aborted mid-resolution
+ */
+export declare function resolveDefinition(source: DefinitionSource, options: ResolveOptions): Promise<DefinitionBundle>;