@llm4ts/shell 2.11.0 → 2.13.0

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

@@ -0,0 +1,453 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+// A strict reader for the narrow XML profile SOAP estates use: WSDL, XSD,
+// SOAP envelopes, and SoapUI project files. It is deliberately not a general
+// XML parser. Document type declarations are refused outright, so external
+// entities (XXE) and entity expansion attacks are impossible by construction;
+// only the five predefined entities and numeric character references are
+// understood. Namespaces are resolved while parsing, and every element keeps
+// its in-scope bindings so QName-valued attributes (`type="tns:Conto"`) can be
+// resolved later.
+export const XmlNamespace = "http://www.w3.org/XML/1998/namespace";
+const XmlnsNamespace = "http://www.w3.org/2000/xmlns/";
+export class XmlError extends Schema.TaggedError()("XmlError", {
+    reason: Schema.Literals(["doctype", "encoding", "syntax", "namespace", "limit"]),
+    detail: Schema.String,
+    line: Schema.optionalKey(Schema.Int),
+    source: Schema.optionalKey(Schema.String)
+}) {
+    get message() {
+        const where = this.source === undefined ? "" : `${this.source}`;
+        const line = this.line === undefined ? "" : `:${this.line}`;
+        const prefix = where === "" && line === "" ? "" : `${where}${line}: `;
+        return `${prefix}${this.reason}: ${this.detail}`;
+    }
+}
+export const defaultXmlLimits = { maxDepth: 256, maxChars: 32 * 1024 * 1024 };
+// ---------------------------------------------------------------------------
+// Decoding
+const encodingDeclaration = /^<\?xml[^>]*?\sencoding\s*=\s*["']([A-Za-z0-9._-]+)["']/;
+const supportedEncodings = new Map([
+    ["utf-8", "utf-8"],
+    ["utf8", "utf-8"],
+    ["us-ascii", "utf-8"],
+    ["ascii", "utf-8"],
+    ["iso-8859-1", "latin1"],
+    ["latin1", "latin1"],
+    ["latin-1", "latin1"],
+    ["iso-8859-15", "iso-8859-15"],
+    ["windows-1252", "windows-1252"],
+    ["cp1252", "windows-1252"],
+    ["utf-16", "utf-16le"],
+    ["utf-16le", "utf-16le"],
+    ["utf-16be", "utf-16be"]
+]);
+const startsWith = (bytes, prefix) => prefix.every((value, index) => bytes[index] === value);
+/**
+ * Decode raw document bytes by BOM, then by the XML declaration's
+ * `encoding`, defaulting to UTF-8. Undecodable input is an `XmlError`, never
+ * replacement characters.
+ */
+export const decodeXml = (bytes, source) => Effect.suspend(() => {
+    const at = source === undefined ? {} : { source };
+    let label = "utf-8";
+    let offset = 0;
+    if (startsWith(bytes, [0xef, 0xbb, 0xbf])) {
+        offset = 3;
+    }
+    else if (startsWith(bytes, [0xff, 0xfe])) {
+        label = "utf-16le";
+        offset = 2;
+    }
+    else if (startsWith(bytes, [0xfe, 0xff])) {
+        label = "utf-16be";
+        offset = 2;
+    }
+    else {
+        const head = String.fromCharCode(...bytes.subarray(0, 200));
+        const declared = encodingDeclaration.exec(head)?.[1]?.toLowerCase();
+        if (declared !== undefined) {
+            const mapped = supportedEncodings.get(declared);
+            if (mapped === undefined) {
+                return Effect.fail(new XmlError({ reason: "encoding", detail: `unsupported encoding ${declared}`, ...at }));
+            }
+            label = mapped;
+        }
+    }
+    return Effect.try({
+        try: () => new TextDecoder(label, { fatal: true }).decode(bytes.subarray(offset)),
+        catch: () => new XmlError({ reason: "encoding", detail: `bytes are not valid ${label}`, ...at })
+    });
+});
+// ---------------------------------------------------------------------------
+// Parsing
+const namePattern = /[A-Za-z_À-￿][A-Za-z0-9._\-·À-￿]*(?::[A-Za-z_À-￿][A-Za-z0-9._\-·À-￿]*)?/y;
+const predefinedEntities = {
+    lt: "<",
+    gt: ">",
+    amp: "&",
+    quot: '"',
+    apos: "'"
+};
+const splitQName = (qname) => {
+    const colon = qname.indexOf(":");
+    return colon < 0
+        ? { prefix: "", local: qname }
+        : { prefix: qname.slice(0, colon), local: qname.slice(colon + 1) };
+};
+class Parser {
+    position = 0;
+    text;
+    limits;
+    source;
+    constructor(text, limits, source) {
+        this.text = text;
+        this.limits = limits;
+        this.source = source;
+    }
+    fail(reason, detail, at = this.position) {
+        throw new XmlError({
+            reason,
+            detail,
+            line: this.lineAt(Math.min(at, this.text.length)),
+            ...(this.source === undefined ? {} : { source: this.source })
+        });
+    }
+    lineAt(at) {
+        let line = 1;
+        for (let index = 0; index < at; index++) {
+            if (this.text.charCodeAt(index) === 10)
+                line++;
+        }
+        return line;
+    }
+    parseDocument() {
+        if (this.text.length > this.limits.maxChars) {
+            this.fail("limit", `document exceeds ${this.limits.maxChars} characters`, 0);
+        }
+        this.skipMisc();
+        if (!this.text.startsWith("<", this.position) || this.position >= this.text.length) {
+            this.fail("syntax", "expected a root element");
+        }
+        const root = this.parseElement(new Map([
+            ["xml", XmlNamespace],
+            ["", ""]
+        ]), 1);
+        this.skipMisc();
+        if (this.position < this.text.length) {
+            this.fail("syntax", "content after the root element");
+        }
+        return root;
+    }
+    /** Whitespace, comments, and processing instructions (including the XML declaration). */
+    skipMisc() {
+        for (;;) {
+            this.skipWhitespace();
+            if (this.text.startsWith("<?", this.position)) {
+                this.skipProcessingInstruction();
+            }
+            else if (this.text.startsWith("<!--", this.position)) {
+                this.skipComment();
+            }
+            else if (this.text.startsWith("<!", this.position)) {
+                this.rejectDeclaration();
+            }
+            else {
+                return;
+            }
+        }
+    }
+    rejectDeclaration() {
+        if (this.text.startsWith("<!DOCTYPE", this.position)) {
+            this.fail("doctype", "document type declarations are not accepted");
+        }
+        return this.fail("syntax", "unexpected markup declaration");
+    }
+    skipWhitespace() {
+        while (this.position < this.text.length && /\s/.test(this.text[this.position] ?? "")) {
+            this.position++;
+        }
+    }
+    skipProcessingInstruction() {
+        const end = this.text.indexOf("?>", this.position + 2);
+        if (end < 0)
+            this.fail("syntax", "unterminated processing instruction");
+        this.position = end + 2;
+    }
+    skipComment() {
+        const end = this.text.indexOf("-->", this.position + 4);
+        if (end < 0)
+            this.fail("syntax", "unterminated comment");
+        this.position = end + 3;
+    }
+    readName() {
+        namePattern.lastIndex = this.position;
+        const match = namePattern.exec(this.text);
+        if (match === null)
+            this.fail("syntax", "expected a name");
+        this.position += match[0].length;
+        return match[0];
+    }
+    decodeText(raw, start) {
+        if (!raw.includes("&"))
+            return raw;
+        return raw.replace(/&([^;&\s]*);?/g, (whole, body) => {
+            if (!whole.endsWith(";"))
+                this.fail("syntax", `unterminated reference &${body}`, start);
+            if (/^#x[0-9A-Fa-f]+$/.test(body)) {
+                return this.codePoint(Number.parseInt(body.slice(2), 16), whole, start);
+            }
+            if (/^#[0-9]+$/.test(body)) {
+                return this.codePoint(Number.parseInt(body.slice(1), 10), whole, start);
+            }
+            if (body.startsWith("#"))
+                this.fail("syntax", `invalid character reference ${whole}`, start);
+            const value = predefinedEntities[body];
+            if (value === undefined)
+                this.fail("syntax", `undeclared entity ${whole}`, start);
+            return value;
+        });
+    }
+    codePoint(code, whole, start) {
+        if (!Number.isInteger(code) || code <= 0 || code > 0x10ffff) {
+            this.fail("syntax", `invalid character reference ${whole}`, start);
+        }
+        return String.fromCodePoint(code);
+    }
+    readAttributes() {
+        const attributes = [];
+        for (;;) {
+            const before = this.position;
+            this.skipWhitespace();
+            const next = this.text[this.position];
+            if (next === ">" || next === "/" || next === undefined)
+                return attributes;
+            if (this.position === before)
+                this.fail("syntax", "expected whitespace before attribute");
+            const qname = this.readName();
+            this.skipWhitespace();
+            if (this.text[this.position] !== "=")
+                this.fail("syntax", `expected = after ${qname}`);
+            this.position++;
+            this.skipWhitespace();
+            const quote = this.text[this.position];
+            if (quote !== '"' && quote !== "'")
+                this.fail("syntax", `expected quoted value for ${qname}`);
+            const end = this.text.indexOf(quote, this.position + 1);
+            if (end < 0)
+                this.fail("syntax", `unterminated value for ${qname}`);
+            const raw = this.text.slice(this.position + 1, end);
+            if (raw.includes("<"))
+                this.fail("syntax", `'<' in value of ${qname}`);
+            const value = this.decodeText(raw, this.position);
+            this.position = end + 1;
+            if (attributes.some((attribute) => attribute.qname === qname)) {
+                this.fail("syntax", `duplicate attribute ${qname}`);
+            }
+            attributes.push({ qname, value });
+        }
+    }
+    parseElement(parentScope, depth) {
+        if (depth > this.limits.maxDepth) {
+            this.fail("limit", `nesting exceeds ${this.limits.maxDepth} levels`);
+        }
+        const start = this.position;
+        this.position++; // "<"
+        const qname = this.readName();
+        const raw = this.readAttributes();
+        const declarations = raw.filter((attribute) => attribute.qname === "xmlns" || attribute.qname.startsWith("xmlns:"));
+        let scope = parentScope;
+        if (declarations.length > 0) {
+            const extended = new Map(parentScope);
+            for (const attribute of declarations) {
+                const prefix = attribute.qname === "xmlns" ? "" : attribute.qname.slice(6);
+                if (prefix !== "" && attribute.value === "") {
+                    this.fail("namespace", `prefix ${prefix} cannot be unbound`, start);
+                }
+                extended.set(prefix, attribute.value);
+            }
+            scope = extended;
+        }
+        const resolve = (name, isAttribute) => {
+            const { prefix, local } = splitQName(name);
+            if (prefix === "") {
+                return { name: { namespace: isAttribute ? "" : (scope.get("") ?? ""), local }, prefix };
+            }
+            if (prefix === "xmlns")
+                return { name: { namespace: XmlnsNamespace, local }, prefix };
+            const namespace = scope.get(prefix);
+            if (namespace === undefined)
+                this.fail("namespace", `unbound prefix ${prefix}`, start);
+            return { name: { namespace, local }, prefix };
+        };
+        const element = resolve(qname, false);
+        const attributes = raw
+            .filter((attribute) => !declarations.includes(attribute))
+            .map((attribute) => {
+            const resolved = resolve(attribute.qname, true);
+            return { name: resolved.name, prefix: resolved.prefix, value: attribute.value };
+        });
+        const line = this.lineAt(start);
+        if (this.text.startsWith("/>", this.position)) {
+            this.position += 2;
+            return {
+                _tag: "element",
+                name: element.name,
+                prefix: element.prefix,
+                attributes,
+                children: [],
+                scope,
+                line
+            };
+        }
+        if (this.text[this.position] !== ">")
+            this.fail("syntax", `malformed start tag <${qname}>`);
+        this.position++;
+        const children = [];
+        let text = "";
+        const flush = () => {
+            if (text !== "") {
+                children.push({ _tag: "text", value: text });
+                text = "";
+            }
+        };
+        for (;;) {
+            if (this.position >= this.text.length)
+                this.fail("syntax", `unclosed element <${qname}>`);
+            const next = this.text.indexOf("<", this.position);
+            if (next < 0)
+                this.fail("syntax", `unclosed element <${qname}>`);
+            if (next > this.position) {
+                const chunk = this.text.slice(this.position, next);
+                text += this.decodeText(chunk, this.position);
+                this.position = next;
+            }
+            if (this.text.startsWith("</", this.position)) {
+                this.position += 2;
+                const closing = this.readName();
+                this.skipWhitespace();
+                if (this.text[this.position] !== ">")
+                    this.fail("syntax", `malformed end tag </${closing}>`);
+                this.position++;
+                if (closing !== qname) {
+                    this.fail("syntax", `</${closing}> does not close <${qname}>`);
+                }
+                flush();
+                return {
+                    _tag: "element",
+                    name: element.name,
+                    prefix: element.prefix,
+                    attributes,
+                    children,
+                    scope,
+                    line
+                };
+            }
+            if (this.text.startsWith("<![CDATA[", this.position)) {
+                const end = this.text.indexOf("]]>", this.position + 9);
+                if (end < 0)
+                    this.fail("syntax", "unterminated CDATA section");
+                text += this.text.slice(this.position + 9, end);
+                this.position = end + 3;
+            }
+            else if (this.text.startsWith("<!--", this.position)) {
+                this.skipComment();
+            }
+            else if (this.text.startsWith("<?", this.position)) {
+                this.skipProcessingInstruction();
+            }
+            else if (this.text.startsWith("<!", this.position)) {
+                this.rejectDeclaration();
+            }
+            else {
+                flush();
+                children.push(this.parseElement(scope, depth + 1));
+            }
+        }
+    }
+}
+/** Parse an already-decoded document into its root element. */
+export const parseXml = (text, options = {}) => Effect.try({
+    // XML end-of-line handling: CRLF and CR become LF before parsing.
+    try: () => new Parser(text.replace(/\r\n?/g, "\n"), options.limits ?? defaultXmlLimits, options.source).parseDocument(),
+    catch: (cause) => cause instanceof XmlError
+        ? cause
+        : new XmlError({
+            reason: "syntax",
+            detail: "unreadable document",
+            ...(options.source === undefined ? {} : { source: options.source })
+        })
+});
+/** Decode bytes by their declared encoding, then parse. */
+export const parseXmlBytes = (bytes, options = {}) => Effect.flatMap(decodeXml(bytes, options.source), (text) => parseXml(text, options));
+// ---------------------------------------------------------------------------
+// Navigation helpers
+export const isElement = (node) => node._tag === "element";
+export const elements = (element) => element.children.filter(isElement);
+export const is = (element, namespace, local) => element.name.namespace === namespace && element.name.local === local;
+export const childrenNamed = (element, namespace, local) => elements(element).filter((child) => is(child, namespace, local));
+export const firstChild = (element, namespace, local) => elements(element).find((child) => is(child, namespace, local));
+/** An unqualified attribute's value (the usual case in WSDL and XSD). */
+export const attribute = (element, local, namespace = "") => element.attributes.find((candidate) => candidate.name.local === local && candidate.name.namespace === namespace)?.value;
+/** Concatenated text content of the element's direct text children. */
+export const textOf = (element) => element.children
+    .filter((child) => child._tag === "text")
+    .map((child) => child.value)
+    .join("");
+/**
+ * Resolve a QName-valued attribute (`tns:Conto`) against the element's
+ * in-scope bindings; an unprefixed value takes the default namespace, as
+ * XSD's `type`/`ref`/`base` do.
+ */
+export const resolveQName = (element, value) => {
+    const { prefix, local } = splitQName(value.trim());
+    const namespace = element.scope.get(prefix);
+    return namespace === undefined ? undefined : { namespace, local };
+};
+// ---------------------------------------------------------------------------
+// Writing
+export const escapeText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+export const escapeAttribute = (value) => escapeText(value).replace(/"/g, "&quot;");
+const qualifiedName = (prefix, local) => prefix === "" ? local : `${prefix}:${local}`;
+/**
+ * Serialize an element tree. Namespace declarations are re-emitted where an
+ * element's scope differs from its parent's, so a parsed tree round-trips to
+ * an equivalent document (whitespace and prefixes kept, comments dropped).
+ */
+export const renderXml = (root, options = {}) => {
+    const out = [];
+    if (options.declaration === true)
+        out.push('<?xml version="1.0" encoding="UTF-8"?>\n');
+    const walk = (element, parentScope) => {
+        const declarations = [];
+        for (const [prefix, namespace] of element.scope) {
+            if (prefix === "xml")
+                continue;
+            if (parentScope.get(prefix) !== namespace) {
+                declarations.push(prefix === ""
+                    ? ` xmlns="${escapeAttribute(namespace)}"`
+                    : ` xmlns:${prefix}="${escapeAttribute(namespace)}"`);
+            }
+        }
+        const attributes = element.attributes.map((attribute) => ` ${qualifiedName(attribute.prefix, attribute.name.local)}="${escapeAttribute(attribute.value)}"`);
+        const name = qualifiedName(element.prefix, element.name.local);
+        out.push(`<${name}${declarations.join("")}${attributes.join("")}`);
+        if (element.children.length === 0) {
+            out.push("/>");
+            return;
+        }
+        out.push(">");
+        for (const child of element.children) {
+            if (child._tag === "text")
+                out.push(escapeText(child.value));
+            else
+                walk(child, element.scope);
+        }
+        out.push(`</${name}>`);
+    };
+    walk(root, new Map([
+        ["xml", XmlNamespace],
+        ["", ""]
+    ]));
+    return out.join("");
+};