@techspokes/typescript-wsdl-client 1.1.4 → 1.1.8

package/dist/loader/schemaInput.js

@@ -0,0 +1,249 @@
+/** Contextual schema traversal; consumes ordered syntax, never payload hints. */
+import { parseOrderedSyntax, SchemaLoadingError, syntaxAttribute, syntaxElements, XSD_NAMESPACE, WSDL_NAMESPACE } from "./orderedSyntax.js";
+import { SchemaResourceLoader, resolveResourceUri } from "./schemaResources.js";
+import { resolutionDepthBound } from "./resolutionDepth.js";
+import { normalizeWhitespace } from '../util/xmlWhitespace.js';
+// Source-syntax evidence is issued only by this loader, never by a copied shape.
+const loadedInputs = new WeakSet();
+// Private original authorized snapshot; never reconstructed from syntax/digests.
+const originalSources = new WeakMap();
+/** Internal bridge for one retained-source invocation. Returned bytes are data, not authority. */
+export function copyOriginalSchemaResource(input, uri, chargeWork) {
+    assertLoadedSchemaInput(input);
+    const bytes = originalSources.get(input)?.get(uri);
+    if (!bytes)
+        throw new TypeError('Original semantic source bytes unavailable');
+    chargeWork(512 + bytes.byteLength * 8);
+    return new Uint8Array(bytes);
+}
+export function assertLoadedSchemaInput(input) {
+    if (!loadedInputs.has(input))
+        throw new TypeError("Unauthenticated loaded schema input");
+}
+export function schemaInterpretationKey(node, targetNamespace, context) {
+    return JSON.stringify([node.source.digest, node.source.uri, node.baseUri, targetNamespace, context.kind, context.namespace, node.source.path]);
+}
+/** Prepare a closed input set from independently authorized physical metadata snapshots.
+ * @remarks Logical import URIs never initiate I/O here. The later native loader still checks their explicit origin/root
+ *   permissions. Missing snapshots refuse rather than falling back to network or to artifact-embedded bytes.
+ * @returns The actual physical root URI and complete offline loading configuration.
+ * @throws SchemaLoadingError For non-file physical inputs, duplicates, denied roots or unavailable files.
+ */
+export async function prepareSchemaSnapshotFiles(root, files, options) {
+    const physical = async (reference) => {
+        if (new URL(resolveResourceUri(reference)).protocol !== 'file:')
+            throw new SchemaLoadingError('unsupported-capability', 'Physical schema snapshot file required');
+        return loader.fetchResource(reference);
+    };
+    const loader = await SchemaResourceLoader.create({ fileRoots: options.policy.fileRoots }, options.limits, undefined, options.chargeWork, options.signal);
+    const source = await physical(root), offlineResources = new Map([[source.uri, source]]);
+    for (const entry of files) {
+        options.chargeWork?.(1);
+        const uri = resolveResourceUri(entry.uri);
+        if (offlineResources.has(uri))
+            throw new SchemaLoadingError('invalid-schema', 'Duplicate logical schema snapshot');
+        offlineResources.set(uri, { ...await physical(entry.file), canonicalUri: entry.canonicalUri });
+    }
+    return { source: source.uri, loading: { ...options, offlineResources } };
+}
+/** A fresh compilation-scoped snapshot, with no implicit network or filesystem permission. */
+export function loadSchemaInput(source, options) {
+    return loadSchemaInputWithValues(source, options, false);
+}
+/** Internal faithful source entry; preserves syntax and the legacy public entry. */
+export function loadSemanticSchemaInput(source, options) {
+    return loadSchemaInputWithValues(source, options, true);
+}
+async function loadSchemaInputWithValues(source, options, semanticValues) {
+    // @why Snapshot caller configuration before the first asynchronous resource read.
+    const namespaceLocations = new Map();
+    if (options.namespaceLocations)
+        for (const [namespace, location] of options.namespaceLocations) {
+            if (typeof namespace !== 'string' || typeof location !== 'string' || !location)
+                throw new TypeError('Namespace locations require string namespace names and nonempty resource locations');
+            options.chargeWork?.(256 + (namespace.length + location.length) * 32);
+            namespaceLocations.set(namespace, resolveResourceUri(location));
+        }
+    const loader = await SchemaResourceLoader.create(options.policy, options.limits, options.offlineResources, options.chargeWork, options.signal);
+    const documents = new Map();
+    const originalBytes = new Map();
+    const schemas = new Map();
+    const edges = [];
+    const active = new Set();
+    const wsdlVisited = new Set();
+    const depthGraph = new Map();
+    const depthTargets = new Map();
+    const recordDepthArc = (from, to, cost) => {
+        const target = JSON.stringify([to, cost]);
+        const targets = depthTargets.get(from) ?? new Set();
+        if (targets.has(target))
+            return;
+        targets.add(target);
+        depthTargets.set(from, targets);
+        const arcs = depthGraph.get(from) ?? [];
+        arcs.push({ to, cost });
+        depthGraph.set(from, arcs);
+    };
+    const recordEdge = (edge) => {
+        options.chargeWork?.(256);
+        const frozen = Object.freeze(edge);
+        edges.push(frozen);
+        if (edge.to)
+            recordDepthArc(edge.from, edge.to, 1);
+    };
+    const checkDepth = (depth, node) => {
+        if (depth > loader.limits.resolutionDepth)
+            throw new SchemaLoadingError("resource-limit", `Schema resolution depth exceeds ${loader.limits.resolutionDepth} edges`, node?.source);
+    };
+    const getDocument = async (uri) => {
+        const resource = await loader.fetchResource(uri);
+        let doc = documents.get(resource.uri);
+        if (!doc) {
+            doc = parseOrderedSyntax(resource.bytes, resource.uri, { maxDepth: loader.limits.syntaxDepth, metadataEncoding: true });
+            if (semanticValues) {
+                options.chargeWork?.(128);
+                originalBytes.set(resource.uri, resource.bytes);
+            }
+            documents.set(resource.uri, doc);
+            options.onDocument?.(doc);
+        }
+        return doc;
+    };
+    const is = (node, namespace, local) => node.name.namespace === namespace && node.name.local === local;
+    // Only XSD anyURI properties use this mapping. Original syntax and namespace
+    // bindings, WSDL transport names, and arbitrary resource URLs remain intact.
+    // Source byte/resource limits govern this phase, before semantic preparation.
+    const xsdUri = (node, name) => {
+        const value = syntaxAttribute(node, name);
+        options.chargeWork?.(64 + (value?.length ?? 0) * 16);
+        return value === undefined || !semanticValues ? value : normalizeWhitespace(value, 'collapse');
+    };
+    // Cached interpretations still consume resolution depth on a later, deeper route.
+    const checkCachedDepth = (key, depth) => {
+        if (depth + resolutionDepthBound(key, depthGraph, active) > loader.limits.resolutionDepth) {
+            throw new SchemaLoadingError("resource-limit", `Schema resolution depth exceeds ${loader.limits.resolutionDepth} edges`, schemas.get(key)?.syntax.source ?? documents.get(key)?.root.source);
+        }
+    };
+    const referencedDocument = async (reference, node) => {
+        try {
+            const referenceUri = resolveResourceUri(reference, node.baseUri);
+            if (new URL(node.source.uri).protocol !== 'file:' && new URL(referenceUri).protocol === 'file:') {
+                throw new SchemaLoadingError('unsupported-capability', 'Remote metadata cannot select local resources');
+            }
+            return { referenceUri, doc: await getDocument(referenceUri) };
+        }
+        catch (error) {
+            if (error instanceof SchemaLoadingError && !error.source)
+                throw new SchemaLoadingError(error.category, error.message, node.source);
+            throw error;
+        }
+    };
+    const interpret = async (node, context, depth) => {
+        options.chargeWork?.(4096 + (node.source.path.length + node.source.uri.length + node.baseUri.length + context.namespace.length) * 32 + node.children.length * 128);
+        checkDepth(depth, node);
+        if (!is(node, XSD_NAMESPACE, "schema"))
+            throw new SchemaLoadingError("invalid-schema", "Expected an XSD schema root", node.source);
+        const declaredValue = xsdUri(node, "targetNamespace");
+        if (semanticValues && declaredValue === '')
+            throw new SchemaLoadingError("invalid-schema", "A present schema target namespace must not be empty", node.source);
+        const declaredNamespace = declaredValue ?? "";
+        const targetNamespace = context.kind === "include" && !declaredNamespace ? context.namespace : declaredNamespace;
+        if (context.kind === "include" && declaredNamespace && declaredNamespace !== context.namespace) {
+            throw new SchemaLoadingError("invalid-schema", "Included schema target namespace differs from its including schema", node.source);
+        }
+        if (context.kind === "import" && targetNamespace !== context.namespace) {
+            throw new SchemaLoadingError("invalid-schema", "Imported schema target namespace differs from the declared import namespace", node.source);
+        }
+        const key = schemaInterpretationKey(node, targetNamespace, context);
+        if (schemas.has(key)) {
+            if (!active.has(key))
+                checkCachedDepth(key, depth);
+            return key;
+        }
+        const instance = Object.freeze({ key, syntax: node, documentUri: node.source.uri, digest: node.source.digest, baseUri: node.baseUri, targetNamespace, context: Object.freeze(context) });
+        schemas.set(key, instance);
+        active.add(key);
+        for (const child of syntaxElements(node, XSD_NAMESPACE)) {
+            if (child.name.local !== "include" && child.name.local !== "import")
+                continue;
+            const kind = child.name.local;
+            const location = xsdUri(child, "schemaLocation");
+            const importedNamespace = xsdUri(child, "namespace");
+            const missingLocation = semanticValues ? location === undefined : !location;
+            if (missingLocation && kind === "include")
+                throw new SchemaLoadingError("invalid-schema", "Schema include requires schemaLocation", child.source);
+            const suppliedLocation = missingLocation && kind === 'import' ? namespaceLocations.get(importedNamespace ?? '') : undefined;
+            if (missingLocation && suppliedLocation === undefined) {
+                recordEdge({ kind, from: key, source: child.source, cycle: false });
+                continue;
+            }
+            checkDepth(depth + 1, child);
+            const namespace = kind === "include" ? targetNamespace : importedNamespace ?? "";
+            if (kind === "import" && namespace === targetNamespace)
+                throw new SchemaLoadingError("invalid-schema", "Schema import must name a different namespace", child.source);
+            const { referenceUri, doc } = await referencedDocument(suppliedLocation ?? location, child);
+            const childDeclaredNamespace = xsdUri(doc.root, "targetNamespace");
+            // A successfully supplied import referent must match both presence and
+            // value. An explicit empty import namespace without a referent is not
+            // by itself forbidden by the anyURI datatype or src-import clause 3.
+            if (semanticValues && kind === 'import' && (importedNamespace === undefined) !== (childDeclaredNamespace === undefined)) {
+                throw new SchemaLoadingError("invalid-schema", "Imported schema target namespace presence differs from the declared import namespace", child.source);
+            }
+            const childContext = { kind, namespace };
+            const childNamespace = kind === "include" ? childDeclaredNamespace || namespace : childDeclaredNamespace ?? "";
+            const childKey = schemaInterpretationKey(doc.root, childNamespace, childContext);
+            const cycle = active.has(childKey);
+            const to = await interpret(doc.root, childContext, depth + 1);
+            recordEdge({ kind, from: key, to, referenceUri, source: child.source, cycle });
+        }
+        active.delete(key);
+        return key;
+    };
+    const visitWsdl = async (doc, depth) => {
+        checkDepth(depth, doc.root);
+        if (!is(doc.root, WSDL_NAMESPACE, "definitions"))
+            throw new SchemaLoadingError("invalid-schema", "Expected WSDL 1.1 definitions", doc.root.source);
+        if (wsdlVisited.has(doc.uri)) {
+            if (!active.has(doc.uri))
+                checkCachedDepth(doc.uri, depth);
+            return;
+        }
+        wsdlVisited.add(doc.uri);
+        active.add(doc.uri);
+        for (const child of syntaxElements(doc.root, WSDL_NAMESPACE)) {
+            if (child.name.local === "types") {
+                for (const schema of syntaxElements(child, XSD_NAMESPACE, "schema")) {
+                    const key = await interpret(schema, { kind: "inline", namespace: "" }, depth);
+                    recordDepthArc(doc.uri, key, 0);
+                }
+            }
+            else if (child.name.local === "import") {
+                const location = syntaxAttribute(child, "location");
+                if (!location)
+                    throw new SchemaLoadingError("invalid-schema", "WSDL import requires location", child.source);
+                checkDepth(depth + 1, child);
+                const { referenceUri, doc: imported } = await referencedDocument(location, child);
+                if ((syntaxAttribute(imported.root, "targetNamespace") ?? "") !== (syntaxAttribute(child, "namespace") ?? "")) {
+                    throw new SchemaLoadingError("invalid-schema", "WSDL import namespace mismatch", child.source);
+                }
+                const cycle = active.has(imported.uri);
+                await visitWsdl(imported, depth + 1);
+                recordEdge({ kind: "wsdl-import", from: doc.uri, to: imported.uri, referenceUri, source: child.source, cycle });
+            }
+        }
+        active.delete(doc.uri);
+    };
+    const root = await getDocument(resolveResourceUri(source));
+    if (is(root.root, XSD_NAMESPACE, "schema"))
+        await interpret(root.root, { kind: "root", namespace: "" }, 0);
+    else if (is(root.root, WSDL_NAMESPACE, "definitions"))
+        await visitWsdl(root, 0);
+    else
+        throw new SchemaLoadingError("unsupported-capability", "Only WSDL 1.1 or XSD schema inputs are accepted; payload hints cannot resolve schemas", root.root.source);
+    const input = Object.freeze({ root, documents: Object.freeze([...documents.values()]), schemas: Object.freeze([...schemas.values()]),
+        resources: loader.metadata, resourceAliases: loader.resourceAliases, edges: Object.freeze(edges), limits: loader.limits, metrics: loader.metrics });
+    loadedInputs.add(input);
+    if (semanticValues)
+        originalSources.set(input, originalBytes);
+    return input;
+}

package/dist/loader/schemaResources.d.ts

@@ -0,0 +1,60 @@
+export declare const DEFAULT_LOADING_LIMITS: Readonly<{
+    resources: 128;
+    resourceBytes: number;
+    totalBytes: number;
+    resolutionDepth: 32;
+    redirects: 5;
+    resourceMs: 15000;
+    totalIoMs: 120000;
+    syntaxDepth: 256;
+}>;
+export type LoadingLimits = Readonly<{
+    [K in keyof typeof DEFAULT_LOADING_LIMITS]: number;
+}>;
+export type SchemaResourcePolicy = Readonly<{
+    fileRoots?: readonly string[];
+    /** Exact HTTP(S) origins, including ports. No implicit host or scheme permission. */
+    allowedOrigins?: readonly string[];
+}>;
+export type OfflineSchemaResource = Readonly<{
+    bytes: Uint8Array;
+    digest: string;
+    canonicalUri?: string;
+}>;
+export type ResourceMetadata = Readonly<{
+    uri: string;
+    digest: string;
+    byteLength: number;
+}>;
+export type FetchedSchemaResource = ResourceMetadata & Readonly<{
+    bytes: Uint8Array;
+}>;
+export declare function loadingLimits(overrides?: Partial<LoadingLimits>): LoadingLimits;
+/** Canonical URL spelling; queries remain distinct, fragments are not retrieval identity. */
+export declare function resolveResourceUri(reference: string, baseUri?: string): string;
+/** One instance per compilation. Bytes and aliases are confined to this I/O boundary. */
+export declare class SchemaResourceLoader {
+    private readonly roots;
+    private readonly lexicalRoots;
+    private readonly origins;
+    private readonly offline?;
+    private readonly charge?;
+    private readonly signal?;
+    readonly limits: LoadingLimits;
+    private readonly resources;
+    private readonly aliases;
+    private readonly resourceKeys;
+    private totalBytes;
+    private ioMs;
+    private constructor();
+    static create(policy: SchemaResourcePolicy, overrides?: Partial<LoadingLimits>, offline?: ReadonlyMap<string, OfflineSchemaResource>, charge?: (amount: number) => void, signal?: AbortSignal): Promise<SchemaResourceLoader>;
+    get metadata(): readonly ResourceMetadata[];
+    get metrics(): Readonly<{
+        resources: number;
+        totalBytes: number;
+        ioMs: number;
+    }>;
+    get resourceAliases(): ReadonlyMap<string, string>;
+    private authorize;
+    fetchResource(reference: string): Promise<FetchedSchemaResource>;
+}

package/dist/loader/schemaResources.js

@@ -0,0 +1,333 @@
+/** Policy-checked, bounded I/O for schema inputs only. Legacy fetching is separate. */
+import { createHash } from "node:crypto";
+import { open, realpath, lstat } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { SchemaLoadingError } from "./orderedSyntax.js";
+export const DEFAULT_LOADING_LIMITS = Object.freeze({
+    resources: 128, resourceBytes: 8 * 1024 * 1024, totalBytes: 64 * 1024 * 1024,
+    resolutionDepth: 32, redirects: 5, resourceMs: 15_000, totalIoMs: 120_000, syntaxDepth: 256,
+});
+export function loadingLimits(overrides = {}) {
+    const limits = { ...DEFAULT_LOADING_LIMITS, ...overrides };
+    for (const [key, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < (['redirects', 'resourceMs', 'totalIoMs'].includes(key) ? 0 : 1)) {
+            throw new RangeError(`Invalid schema loading limit: ${key}`);
+        }
+    }
+    return Object.freeze(limits);
+}
+/** Canonical URL spelling; queries remain distinct, fragments are not retrieval identity. */
+export function resolveResourceUri(reference, baseUri) {
+    let url;
+    try {
+        url = baseUri ? new URL(reference, baseUri)
+            : /^[a-z][a-z0-9+.-]*:/i.test(reference) && !/^[a-z]:[\\/]/i.test(reference)
+                ? new URL(reference) : pathToFileURL(path.resolve(reference));
+    }
+    catch {
+        throw new SchemaLoadingError("invalid-schema", "Invalid schema resource URI");
+    }
+    if (!["file:", "http:", "https:"].includes(url.protocol)) {
+        throw new SchemaLoadingError("unsupported-capability", "Unsupported schema resource scheme");
+    }
+    if (url.username || url.password)
+        throw new SchemaLoadingError("unsupported-capability", "Credential-bearing resource URIs are forbidden");
+    if (url.protocol === "file:" && (url.search || (url.hostname && url.hostname !== "localhost"))) {
+        throw new SchemaLoadingError("unsupported-capability", "File URI queries and remote file authorities are forbidden");
+    }
+    url.hash = "";
+    return url.href;
+}
+function withinRoot(file, root) {
+    const relative = path.relative(root, file);
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+/** One instance per compilation. Bytes and aliases are confined to this I/O boundary. */
+export class SchemaResourceLoader {
+    roots;
+    lexicalRoots;
+    origins;
+    offline;
+    charge;
+    signal;
+    limits;
+    resources = new Map();
+    aliases = new Map();
+    resourceKeys = new Map();
+    totalBytes = 0;
+    ioMs = 0;
+    constructor(roots, lexicalRoots, origins, limits, offline, charge, signal) {
+        this.roots = roots;
+        this.lexicalRoots = lexicalRoots;
+        this.origins = origins;
+        this.offline = offline;
+        this.charge = charge;
+        this.signal = signal;
+        this.limits = limits;
+    }
+    static async create(policy, overrides, offline, charge, signal) {
+        charge?.(1024 + (policy.fileRoots?.length ?? 0) * 128 + (policy.allowedOrigins?.length ?? 0) * 128 + (offline?.size ?? 0) * 256);
+        const configuredRoots = (policy.fileRoots ?? []).map(root => { charge?.(128 + root.length * 32); return path.resolve(root); });
+        let roots;
+        try {
+            roots = await Promise.all(configuredRoots.map(root => realpath(root)));
+        }
+        catch {
+            throw new SchemaLoadingError("transport", "An authorized schema root is unavailable");
+        }
+        const origins = new Set((policy.allowedOrigins ?? []).map(origin => {
+            charge?.(128 + origin.length * 32);
+            const url = new URL(origin);
+            if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+                throw new RangeError("allowedOrigins must contain HTTP(S) origins only");
+            }
+            return url.origin;
+        }));
+        // Copy the manifest; byte copies occur only after per-resource/aggregate checks.
+        const snapshots = offline ? new Map() : undefined;
+        if (offline)
+            for (const [uri, value] of offline) {
+                charge?.(256 + uri.length * 32);
+                snapshots.set(resolveResourceUri(uri), { bytes: value.bytes, digest: value.digest, canonicalUri: value.canonicalUri });
+            }
+        return new SchemaResourceLoader(roots, [...configuredRoots, ...roots], origins, loadingLimits(overrides), snapshots, charge, signal);
+    }
+    get metadata() {
+        this.charge?.(128 + this.resources.size * 256);
+        return Object.freeze([...this.resources.values()].map(({ uri, digest, byteLength }) => Object.freeze({ uri, digest, byteLength })));
+    }
+    get metrics() {
+        return Object.freeze({ resources: this.resources.size, totalBytes: this.totalBytes, ioMs: this.ioMs });
+    }
+    get resourceAliases() { return new Map(this.aliases); }
+    async authorize(uri) {
+        this.charge?.(1024 + uri.length * 32 + this.roots.length * 256);
+        const url = new URL(resolveResourceUri(uri));
+        if (url.protocol !== "file:") {
+            if (!this.origins.has(url.origin))
+                throw new SchemaLoadingError("unsupported-capability", "Schema resource origin is not authorized");
+            return url.href;
+        }
+        const file = fileURLToPath(url);
+        // Check lexical traversal before touching the filesystem, then symlink-resolved identity.
+        if (!this.lexicalRoots.some(root => withinRoot(file, root)))
+            throw new SchemaLoadingError("unsupported-capability", "Schema file is outside authorized roots");
+        const actual = await realpath(file);
+        if (!this.roots.some(root => withinRoot(actual, root)))
+            throw new SchemaLoadingError("unsupported-capability", "Schema symlink is outside authorized roots");
+        return pathToFileURL(actual).href;
+    }
+    async fetchResource(reference) {
+        this.charge?.(256 + reference.length * 4);
+        const requested = resolveResourceUri(reference);
+        // A previously authorized alias returns the compilation's pinned bytes without new I/O.
+        const pinned = this.resources.get(this.resourceKeys.get(this.aliases.get(requested) ?? requested) ?? "");
+        if (pinned)
+            return pinned;
+        const started = performance.now();
+        const remaining = this.limits.totalIoMs === 0 ? Infinity : this.limits.totalIoMs - this.ioMs;
+        if (remaining < 0)
+            throw new SchemaLoadingError("transport", "Total schema I/O deadline exhausted");
+        const budget = Math.min(this.limits.resourceMs === 0 ? Infinity : this.limits.resourceMs, remaining);
+        const controller = new AbortController();
+        const abort = () => controller.abort(this.signal?.reason);
+        this.signal?.addEventListener('abort', abort, { once: true });
+        if (this.signal?.aborted)
+            abort();
+        let timer;
+        let performedIo = new URL(requested).protocol === "file:";
+        const timeout = new Promise((_, reject) => {
+            // Limits are inclusive: an exactly-at-deadline completed resource is admitted.
+            if (Number.isFinite(budget))
+                timer = setTimeout(() => { controller.abort(); reject(new SchemaLoadingError("transport", "Schema resource or total I/O deadline exceeded")); }, budget + 1);
+        });
+        try {
+            const task = (async () => {
+                let uri = await this.authorize(requested);
+                if (controller.signal.aborted || performance.now() - started > budget)
+                    throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                const cached = this.resources.get(this.resourceKeys.get(this.aliases.get(uri) ?? uri) ?? "");
+                if (cached)
+                    return cached;
+                const checkResourceCount = () => {
+                    if (this.resources.size >= this.limits.resources)
+                        throw new SchemaLoadingError("resource-limit", `Schema resource count exceeds ${this.limits.resources}`);
+                };
+                performedIo = true;
+                const redirectAliases = [requested, uri];
+                const chunks = [];
+                let byteLength = 0;
+                const accept = (chunk) => {
+                    if (controller.signal.aborted || performance.now() - started > budget)
+                        throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                    // Reserve copying, hashing, decoding and bounded syntax preparation before retaining bytes.
+                    this.charge?.(64 + chunk.byteLength * 32);
+                    byteLength += chunk.byteLength;
+                    if (byteLength > this.limits.resourceBytes || this.totalBytes + byteLength > this.limits.totalBytes) {
+                        throw new SchemaLoadingError("resource-limit", "Decompressed schema byte budget exceeded");
+                    }
+                    chunks.push(Uint8Array.from(chunk));
+                };
+                if (this.offline) {
+                    const snapshot = this.offline.get(uri);
+                    if (!snapshot)
+                        throw new SchemaLoadingError("transport", "Schema resource is absent from the offline snapshot");
+                    if (snapshot.bytes.byteLength > this.limits.resourceBytes)
+                        throw new SchemaLoadingError('resource-limit', 'Decompressed schema byte budget exceeded');
+                    const snapshotDigest = (value) => {
+                        if (controller.signal.aborted || performance.now() - started > budget)
+                            throw new SchemaLoadingError('transport', 'Schema I/O deadline exceeded');
+                        this.charge?.(64 + value.bytes.byteLength * 8);
+                        return createHash('sha256').update(value.bytes).digest('hex');
+                    };
+                    if (snapshot.canonicalUri) {
+                        if (new URL(uri).protocol !== 'file:' && new URL(resolveResourceUri(snapshot.canonicalUri)).protocol === 'file:')
+                            throw new SchemaLoadingError('unsupported-capability', 'Remote metadata cannot select local resources');
+                        const canonical = await this.authorize(snapshot.canonicalUri);
+                        const target = this.offline.get(canonical);
+                        if (target && (target.digest !== snapshot.digest || target.bytes.byteLength !== snapshot.bytes.byteLength)) {
+                            throw new SchemaLoadingError('invalid-schema', 'Conflicting offline alias bytes');
+                        }
+                        if (target) {
+                            if (target.bytes.byteLength > this.limits.resourceBytes)
+                                throw new SchemaLoadingError('resource-limit', 'Decompressed schema byte budget exceeded');
+                            if (snapshotDigest(target) !== target.digest)
+                                throw new SchemaLoadingError('invalid-schema', 'Offline schema digest mismatch');
+                            if (target.canonicalUri && resolveResourceUri(target.canonicalUri) !== canonical)
+                                throw new SchemaLoadingError('unsupported-capability', 'Offline aliases must name a canonical snapshot');
+                        }
+                        uri = canonical;
+                        redirectAliases.push(uri);
+                        const cached = this.resources.get(this.resourceKeys.get(uri) ?? '');
+                        if (cached) {
+                            if (snapshot.digest !== cached.digest || snapshotDigest(snapshot) !== snapshot.digest) {
+                                throw new SchemaLoadingError('invalid-schema', 'Conflicting offline alias bytes');
+                            }
+                            for (const alias of redirectAliases)
+                                this.aliases.set(alias, uri);
+                            return cached;
+                        }
+                    }
+                    checkResourceCount();
+                    accept(snapshot.bytes);
+                    const digest = createHash("sha256").update(snapshot.bytes).digest("hex");
+                    if (digest !== snapshot.digest)
+                        throw new SchemaLoadingError("invalid-schema", "Offline schema digest mismatch");
+                }
+                else if (new URL(uri).protocol === "file:") {
+                    checkResourceCount();
+                    const localPath = fileURLToPath(uri);
+                    if (!(await lstat(localPath)).isFile())
+                        throw new SchemaLoadingError("unsupported-capability", "Schema resource must be a regular file");
+                    const file = await open(localPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+                    try {
+                        if (!(await file.stat()).isFile())
+                            throw new SchemaLoadingError("unsupported-capability", "Schema resource must be a regular file");
+                        // @why Cancellation during metadata I/O must not construct an already-aborted stream that can emit outside iterator handling.
+                        if (controller.signal.aborted)
+                            throw new SchemaLoadingError("transport", "Schema resource I/O cancelled");
+                        const stream = file.createReadStream({ autoClose: false, signal: controller.signal });
+                        try {
+                            for await (const chunk of stream)
+                                accept(chunk);
+                        }
+                        finally {
+                            stream.destroy();
+                        }
+                    }
+                    finally {
+                        await file.close();
+                    }
+                }
+                else {
+                    for (let redirects = 0;; redirects++) {
+                        const response = await fetch(uri, { redirect: "manual", signal: controller.signal, headers: { Accept: "application/xml,text/xml" } });
+                        if ([301, 302, 303, 307, 308].includes(response.status)) {
+                            await response.body?.cancel();
+                            if (redirects >= this.limits.redirects)
+                                throw new SchemaLoadingError("resource-limit", `Schema redirects exceed ${this.limits.redirects}`);
+                            const location = response.headers.get("location");
+                            if (!location)
+                                throw new SchemaLoadingError("transport", "Schema redirect has no location");
+                            const redirected = resolveResourceUri(location, uri);
+                            if (new URL(redirected).protocol === "file:")
+                                throw new SchemaLoadingError("unsupported-capability", "HTTP redirects cannot select file resources");
+                            uri = await this.authorize(redirected);
+                            redirectAliases.push(uri);
+                            const redirectedCache = this.resources.get(this.resourceKeys.get(this.aliases.get(uri) ?? uri) ?? "");
+                            if (redirectedCache) {
+                                if (controller.signal.aborted || performance.now() - started > budget)
+                                    throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                                for (const alias of redirectAliases)
+                                    this.aliases.set(alias, redirectedCache.uri);
+                                return redirectedCache;
+                            }
+                            continue;
+                        }
+                        if (!response.ok) {
+                            await response.body?.cancel();
+                            throw new SchemaLoadingError("transport", `Schema retrieval returned HTTP ${response.status}`);
+                        }
+                        if (this.resources.size >= this.limits.resources) {
+                            await response.body?.cancel();
+                            checkResourceCount();
+                        }
+                        // Manual fetch must preserve identity; an opaque/auto-following transport is rejected.
+                        if (response.redirected || (response.url && resolveResourceUri(response.url) !== uri)) {
+                            await response.body?.cancel();
+                            throw new SchemaLoadingError("unsupported-capability", "Schema transport changed retrieval identity without policy checks");
+                        }
+                        const reader = response.body?.getReader();
+                        if (reader) {
+                            const abort = () => { void reader.cancel().catch(() => { }); };
+                            controller.signal.addEventListener("abort", abort, { once: true });
+                            try {
+                                for (;;) {
+                                    const chunk = await reader.read();
+                                    if (chunk.done)
+                                        break;
+                                    accept(chunk.value);
+                                }
+                            }
+                            finally {
+                                controller.signal.removeEventListener("abort", abort);
+                                await reader.cancel().catch(() => { });
+                                reader.releaseLock();
+                            }
+                        }
+                        break;
+                    }
+                }
+                if (controller.signal.aborted || performance.now() - started > budget)
+                    throw new SchemaLoadingError("transport", "Schema I/O deadline exceeded");
+                const bytes = Buffer.concat(chunks, byteLength);
+                const digest = createHash("sha256").update(bytes).digest("hex");
+                const resource = Object.freeze({ uri, digest, byteLength, bytes });
+                // Byte cache identity is (final canonical URI, digest); aliases never change context's final URI.
+                const resourceKey = JSON.stringify([uri, digest]);
+                this.resources.set(resourceKey, resource);
+                this.resourceKeys.set(uri, resourceKey);
+                for (const alias of redirectAliases)
+                    this.aliases.set(alias, uri);
+                this.totalBytes += byteLength;
+                return resource;
+            })();
+            return await Promise.race([task, timeout]);
+        }
+        catch (error) {
+            controller.abort();
+            if (error instanceof SchemaLoadingError)
+                throw error;
+            // Do not expose filesystem paths, response text or credential-bearing transport errors.
+            throw new SchemaLoadingError("transport", "Unable to retrieve schema resource under the configured policy");
+        }
+        finally {
+            this.signal?.removeEventListener('abort', abort);
+            clearTimeout(timer);
+            if (performedIo)
+                this.ioMs += performance.now() - started;
+        }
+    }
+}

package/dist/loader/wsdlLoader.d.ts

@@ -43,4 +43,3 @@ export type WsdlCatalog = {
  * @throws {Error} - If the document is not a valid WSDL 1.1 file
  */
 export declare function loadWsdl(wsdlUrlOrPath: string): Promise<WsdlCatalog>;
-//# sourceMappingURL=wsdlLoader.d.ts.map

package/dist/openapi/casing.d.ts

@@ -21,4 +21,3 @@ export type PathStyle = "kebab" | "asis" | "lower";
  * @returns {string} - Formatted path segment
  */
 export declare function toPathSegment(name: string, style: PathStyle): string;
-//# sourceMappingURL=casing.d.ts.map

package/dist/openapi/generateOpenAPI.d.ts

@@ -83,4 +83,3 @@ export declare function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
     jsonPath?: string;
     yamlPath?: string;
 }>;
-//# sourceMappingURL=generateOpenAPI.d.ts.map