@wirebench/engine 2.1.1

package/dist/wsdl/update-definition.js

@@ -0,0 +1,314 @@
+/**
+ * "Update Definition": re-import a WSDL and reconcile an existing
+ * project against it.
+ *
+ * The two halves are deliberately separate. {@link planUpdate} is a pure diff of
+ * two {@link ImportResult}s — what a preview dialog shows before the user commits
+ * to anything. {@link applyUpdate} then rewrites the project model per the
+ * options the user ticked, and is equally pure: it returns the next `Project`
+ * plus the relative paths of the `.xml.bak` backups the save layer should write
+ * (see `project/save.ts`'s `backups` option), and never touches a file system
+ * itself.
+ *
+ * Nothing is ever deleted. Requests belonging to an operation the new definition
+ * no longer has are kept and flagged {@link RequestDef.orphaned} rather than
+ * removed — the user decides whether a vanished operation means "clean
+ * this up" or "the new WSDL is wrong".
+ */
+import { generateRequest } from '../generate.js';
+import { createRequest, generateId } from '../project/model.js';
+import { INTERFACES_DIR, OPERATIONS_DIR, uniqueSlug } from '../project/paths.js';
+import { recreateRequest } from '../soap/recreate.js';
+import { generateElement, generateType } from '../xsd/sample-generator.js';
+import { findBinding, findPortType } from './model.js';
+import { qnameToString } from './qname.js';
+/**
+ * Generation options the diff compares envelopes under. Optional content is
+ * deliberately *included*: an added `minOccurs="0"` element is a real schema
+ * change the user must be told about, even though the default sample envelope
+ * would not show it.
+ */
+const DIFF_GENERATE_OPTIONS = { includeOptional: true, typeComments: false, sampleValues: false };
+/** An operation's identity across two definitions: its binding's expanded name plus its own name. */
+function operationKey(ref) {
+    return `${qnameToString(ref.bindingName)}#${ref.operationName}`;
+}
+function refOf(summary) {
+    return { bindingName: summary.bindingName, operationName: summary.operationName };
+}
+/** Every `soap:address` the definition exposes, deduplicated, in document order. */
+function addressesOf(summary) {
+    const seen = new Set();
+    for (const operation of summary) {
+        for (const port of operation.ports) {
+            if (port.address !== undefined) {
+                seen.add(port.address);
+            }
+        }
+    }
+    return [...seen];
+}
+/** The generated sample envelope for one operation, or `undefined` when it cannot be built. */
+function envelopeOf(result, ref) {
+    try {
+        return generateRequest(result, ref, DIFF_GENERATE_OPTIONS).envelopeXml;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A structural fingerprint of one operation's output message: every part, with
+ * the sample fragment its element/type would generate. There is no response
+ * builder in the engine, so this stands in for "the response shape changed".
+ */
+function outputSignature(definition, schemaSet, ref) {
+    const binding = findBinding(definition, ref.bindingName);
+    if (binding === undefined) {
+        return '';
+    }
+    const portType = findPortType(definition, binding.type);
+    const operation = portType?.operations.find((candidate) => candidate.name === ref.operationName);
+    const output = operation?.output;
+    if (output === undefined) {
+        return '';
+    }
+    const message = definition.messages.find((candidate) => qnameToString(candidate.name) === qnameToString(output.message));
+    if (message === undefined) {
+        return qnameToString(output.message);
+    }
+    const parts = message.parts.map((part) => {
+        try {
+            if (part.element !== undefined) {
+                return `${part.name}=${generateElement(schemaSet, part.element, DIFF_GENERATE_OPTIONS).xml}`;
+            }
+            if (part.type !== undefined) {
+                const name = { namespaceUri: '', localName: part.name };
+                return `${part.name}=${generateType(schemaSet, name, part.type, DIFF_GENERATE_OPTIONS).xml}`;
+            }
+        }
+        catch {
+            /* An unresolvable part contributes its declared name only. */
+        }
+        return `${part.name}=?`;
+    });
+    return parts.join('\n');
+}
+/** The first reason `next` differs from `previous`, or `undefined` when they match. */
+function changeReason(oldImport, newImport, previous, next) {
+    if (previous.soapAction !== next.soapAction) {
+        return 'soap-action';
+    }
+    if (previous.style !== next.style) {
+        return 'style';
+    }
+    if (previous.soapVersion !== next.soapVersion) {
+        return 'binding';
+    }
+    if (envelopeOf(oldImport, refOf(previous)) !== envelopeOf(newImport, refOf(next))) {
+        return 'input-schema';
+    }
+    const ref = refOf(next);
+    if (outputSignature(oldImport.definition, oldImport.schemaSet, ref) !==
+        outputSignature(newImport.definition, newImport.schemaSet, ref)) {
+        return 'output-schema';
+    }
+    return undefined;
+}
+/**
+ * Diffs two imports of the same interface: what the new definition adds, drops
+ * and changes. Operation identity is the binding's expanded name plus the
+ * operation name, so a renamed binding reads as "every operation removed, every
+ * operation added" — which is what it is.
+ *
+ * Pure and deterministic: the lists follow the new definition's document order
+ * (removed operations follow the old one's).
+ *
+ * @param oldImport the definition the project was built from
+ * @param newImport the freshly fetched definition
+ */
+export function planUpdate(oldImport, newImport) {
+    const oldByKey = new Map(oldImport.operations.map((op) => [operationKey(refOf(op)), op]));
+    const newByKey = new Map(newImport.operations.map((op) => [operationKey(refOf(op)), op]));
+    const newOperations = [];
+    const changedOperations = [];
+    for (const [key, next] of newByKey) {
+        const previous = oldByKey.get(key);
+        if (previous === undefined) {
+            newOperations.push(refOf(next));
+            continue;
+        }
+        const reason = changeReason(oldImport, newImport, previous, next);
+        if (reason !== undefined) {
+            changedOperations.push({ ref: refOf(next), reason });
+        }
+    }
+    const removedOperations = [];
+    for (const [key, previous] of oldByKey) {
+        if (!newByKey.has(key)) {
+            removedOperations.push(refOf(previous));
+        }
+    }
+    const oldAddresses = addressesOf(oldImport.operations);
+    const newAddresses = addressesOf(newImport.operations);
+    return {
+        newOperations,
+        removedOperations,
+        changedOperations,
+        endpointsAdded: newAddresses.filter((address) => !oldAddresses.includes(address)),
+        endpointsRemoved: oldAddresses.filter((address) => !newAddresses.includes(address)),
+    };
+}
+function requireInterface(project, interfaceId) {
+    const iface = project.interfaces.find((candidate) => candidate.id === interfaceId);
+    if (iface === undefined) {
+        throw new Error(`No interface with id "${interfaceId}"`);
+    }
+    return iface;
+}
+/** The `.xml.bak` path of one saved request, relative to the project root. */
+function backupPath(iface, operation, request) {
+    return `${INTERFACES_DIR}/${iface.slug}/${OPERATIONS_DIR}/${operation.slug}/${request.slug}.xml.bak`;
+}
+/** The operation summary for `ref` in the new import, if the new definition still has it. */
+function summaryFor(result, key) {
+    return result.operations.find((op) => operationKey(refOf(op)) === key);
+}
+/** Adds the endpoints `plan.endpointsAdded` names, skipping URLs the interface already has. */
+function withAddedEndpoints(iface, plan, newId) {
+    const known = new Set(iface.endpoints.map((endpoint) => endpoint.url));
+    const added = plan.endpointsAdded
+        .filter((url) => !known.has(url))
+        .map((url) => ({ id: newId(), name: url, url, authMode: 'complement' }));
+    if (added.length === 0) {
+        return iface;
+    }
+    const endpoints = [...iface.endpoints, ...added];
+    return {
+        ...iface,
+        endpoints,
+        ...(iface.defaultEndpointId === undefined && endpoints[0] !== undefined
+            ? { defaultEndpointId: endpoints[0].id }
+            : {}),
+    };
+}
+/**
+ * Applies `plan` to one interface of `project`, per `options`.
+ *
+ * Never deletes anything: a removed operation's requests stay exactly where they
+ * are with `orphaned: true`, and an operation the new definition brought back has
+ * that flag cleared again.
+ *
+ * @param project the model to update; never mutated
+ * @param interfaceId the interface the plan belongs to
+ * @param plan the diff from {@link planUpdate}
+ * @param newImport the freshly imported definition the plan was built against
+ * @param options which of the update behaviours to perform
+ * @throws Error when `interfaceId` names no interface of `project`
+ */
+export function applyUpdate(project, interfaceId, plan, newImport, options) {
+    const newId = options.newId ?? generateId;
+    let iface = requireInterface(project, interfaceId);
+    const requestsCreated = [];
+    const requestsRecreated = [];
+    const requestsOrphaned = [];
+    const backups = [];
+    const removedKeys = new Set(plan.removedOperations.map(operationKey));
+    const changedByKey = new Map(plan.changedOperations.map((changed) => [operationKey(changed.ref), changed]));
+    const generateOptions = { includeOptional: options.recreateOptional };
+    // Pass 1: orphan flags and recreated envelopes, operation by operation.
+    const operations = iface.operations.map((operation) => {
+        const key = `${operation.bindingName}#${operation.name}`;
+        const orphaned = removedKeys.has(key);
+        const recreate = options.recreateRequests && changedByKey.has(key);
+        const requests = operation.requests.map((request) => {
+            let next = request;
+            if (orphaned) {
+                if (request.orphaned !== true) {
+                    requestsOrphaned.push(request.id);
+                }
+                next = { ...next, orphaned: true };
+            }
+            else if (request.orphaned === true) {
+                // `exactOptionalPropertyTypes`: the flag is *absent* again, not `undefined`.
+                next = Object.fromEntries(Object.entries(next).filter(([key]) => key !== 'orphaned'));
+            }
+            if (recreate) {
+                const summary = summaryFor(newImport, key);
+                if (summary !== undefined) {
+                    const generated = generateRequest(newImport, refOf(summary), generateOptions);
+                    const merged = recreateRequest(next.envelopeXml, generated.envelopeXml, {
+                        keepValues: options.keepExisting,
+                        keepHeaders: options.keepSoapHeaders,
+                    });
+                    if (options.createBackups) {
+                        backups.push(backupPath(iface, operation, request));
+                    }
+                    requestsRecreated.push(request.id);
+                    next = {
+                        ...next,
+                        envelopeXml: merged.xml,
+                        soapVersion: generated.soapVersion,
+                        ...(generated.soapAction !== undefined ? { soapAction: generated.soapAction } : {}),
+                    };
+                }
+            }
+            return next;
+        });
+        return { ...operation, requests };
+    });
+    iface = { ...iface, operations };
+    // Pass 2: an operation folder (and its first request) for everything the new definition adds.
+    if (options.createNewRequests) {
+        for (const ref of plan.newOperations) {
+            const summary = summaryFor(newImport, operationKey(ref));
+            if (summary === undefined) {
+                continue;
+            }
+            const bindingName = qnameToString(ref.bindingName);
+            const existing = iface.operations.find((op) => op.bindingName === bindingName && op.name === ref.operationName);
+            const operation = existing ?? {
+                name: ref.operationName,
+                bindingName,
+                slug: uniqueSlug(ref.operationName, new Set(iface.operations.map((op) => op.slug))),
+                order: iface.operations.length,
+                requests: [],
+            };
+            const generated = generateRequest(newImport, ref, generateOptions);
+            const name = 'Request 1';
+            const request = createRequest(name, {
+                id: newId(),
+                envelopeXml: generated.envelopeXml,
+                soapVersion: generated.soapVersion,
+                slug: uniqueSlug(name, new Set(operation.requests.map((r) => r.slug))),
+                order: operation.requests.length,
+                ...(generated.soapAction !== undefined ? { soapAction: generated.soapAction } : {}),
+                ...(iface.defaultEndpointId !== undefined ? { endpointId: iface.defaultEndpointId } : {}),
+            });
+            requestsCreated.push(request.id);
+            const withRequest = { ...operation, requests: [...operation.requests, request] };
+            iface = {
+                ...iface,
+                operations: existing === undefined
+                    ? [...iface.operations, withRequest]
+                    : iface.operations.map((op) => (op === existing ? withRequest : op)),
+            };
+        }
+    }
+    iface = withAddedEndpoints(iface, plan, newId);
+    iface = {
+        ...iface,
+        definitionUrl: newImport.bundle.root.location,
+        ...(newImport.definition.targetNamespace !== '' ? { targetNamespace: newImport.definition.targetNamespace } : {}),
+    };
+    return {
+        project: {
+            ...project,
+            interfaces: project.interfaces.map((candidate) => (candidate.id === interfaceId ? iface : candidate)),
+        },
+        requestsCreated,
+        requestsRecreated,
+        requestsOrphaned,
+        backups,
+    };
+}

package/dist/wss/apply.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Applies (and removes) an outgoing WS-Security header on a SOAP envelope: the
+ * `wsse:Security` block, its `mustUnderstand`/actor attributes, and the configured entries in
+ * configuration order.
+ */
+import type { WssContext, WssOutgoingConfig } from './model.js';
+/** Request-level properties that override an entry's own settings for one send. */
+export interface WssRequestProperties {
+    readonly wssPasswordType?: 'text' | 'digest';
+    readonly wssTimeToLive?: number;
+}
+/** Options accepted by {@link applyOutgoingWss}. */
+export interface ApplyOutgoingWssOptions {
+    readonly requestProperties?: WssRequestProperties;
+}
+/**
+ * Applies `config` to `envelopeXml`, returning the new envelope.
+ *
+ * The `soap:Header` is created (before the `Body`) when missing, the `wsse:Security` block
+ * addressed to `config.actor` is reused when one already exists, and the entries are appended
+ * to it in configuration order. Request-level `wssPasswordType`/`wssTimeToLive` override the
+ * matching entry fields for this application only.
+ *
+ * @param envelopeXml the envelope to secure
+ * @param config the outgoing configuration
+ * @param ctx the injected keystore/secret/clock/entropy capabilities
+ * @param options request-level property overrides
+ * @returns the serialized, secured envelope
+ * @throws WssError `wss-not-an-envelope`, or `wss-entry-unsupported` for an unknown entry kind
+ */
+export declare function applyOutgoingWss(envelopeXml: string, config: WssOutgoingConfig, ctx: WssContext, options?: ApplyOutgoingWssOptions): Promise<string>;
+/**
+ * Removes the `wsse:Security` header addressed to `actor` (the ultimate receiver's when
+ * `actor` is omitted), plus the `soap:Header` if that emptied it.
+ *
+ * @param envelopeXml the envelope to clean
+ * @param actor the actor/role whose Security block to remove
+ * @returns the envelope without that header; unchanged when there is nothing to remove
+ */
+export declare function removeOutgoingWss(envelopeXml: string, actor?: string): string;

package/dist/wss/apply.js

@@ -0,0 +1,212 @@
+/**
+ * Applies (and removes) an outgoing WS-Security header on a SOAP envelope: the
+ * `wsse:Security` block, its `mustUnderstand`/actor attributes, and the configured entries in
+ * configuration order.
+ */
+import { WssError } from '../errors.js';
+import { parseXml } from '../xml/parse.js';
+import { serializeXml } from '../xml/serialize.js';
+import { NS } from '../xml/namespaces.js';
+import { detectEnvelopeVersion, envelopeNamespace } from '../soap/envelope.js';
+import { buildTimestamp } from './outgoing/timestamp.js';
+import { buildUsernameToken } from './outgoing/username-token.js';
+import { signEnvelope } from './outgoing/signature.js';
+import { encryptEnvelope } from './outgoing/encryption.js';
+import { selectAlias } from './keystore/index.js';
+import { actorAttribute, childElement, mustUnderstandValue, securityHeaders, securityActor, } from './security-header.js';
+/** The namespace `xmlns:*` declarations themselves live in. */
+const XMLNS = 'http://www.w3.org/2000/xmlns/';
+/** True when `header` has no element children and only whitespace (or no) text content. */
+function headerHasOnlyWhitespace(header) {
+    for (let node = header.firstChild; node !== null; node = node.nextSibling) {
+        if (node.nodeType === 1) {
+            return false;
+        }
+        if (node.nodeType === 3 && (node.nodeValue ?? '').trim() !== '') {
+            return false;
+        }
+    }
+    return true;
+}
+/** Parses `envelopeXml`, rejecting anything that is not a SOAP envelope. */
+function parseEnvelope(envelopeXml) {
+    const doc = parseXml(envelopeXml, { location: 'envelope' });
+    const version = detectEnvelopeVersion(doc);
+    const root = doc.documentElement;
+    if (version === undefined || root === null) {
+        throw new WssError('wss-not-an-envelope', 'WS-Security can only be applied to a SOAP envelope.');
+    }
+    return { doc, root, version };
+}
+/** The prefix the envelope binds its SOAP namespace to (`soapenv` when it uses a default namespace). */
+function envelopePrefix(root) {
+    const prefix = root.prefix;
+    return prefix === null || prefix === '' ? 'soapenv' : prefix;
+}
+/** Finds or creates the `soap:Header`, always placing a new one before the `Body`. */
+function ensureHeader(doc, root, version) {
+    const namespace = envelopeNamespace(version);
+    const existing = childElement(root, namespace, 'Header');
+    if (existing !== undefined) {
+        return existing;
+    }
+    const header = doc.createElementNS(namespace, `${envelopePrefix(root)}:Header`);
+    const body = childElement(root, namespace, 'Body');
+    root.insertBefore(header, body ?? null);
+    return header;
+}
+/** Finds or creates the `wsse:Security` block addressed to `actor`. */
+function ensureSecurity(doc, root, header, version, config) {
+    const existing = securityHeaders(header).find((element) => securityActor(element, version) === config.actor);
+    const security = existing ?? doc.createElementNS(NS.WSSE, 'wsse:Security');
+    if (existing === undefined) {
+        // `wsse` comes from the element's own name; `wsu` is declared here through the xmlns
+        // namespace (not as a plain attribute) so xmldom records it in the element's namespace map
+        // and the entries below inherit the prefix instead of re-declaring it on every child.
+        security.setAttributeNS(XMLNS, 'xmlns:wsu', NS.WSU);
+        header.appendChild(security);
+    }
+    const prefix = envelopePrefix(root);
+    const envelopeNs = envelopeNamespace(version);
+    if (config.actor !== undefined && config.actor !== '') {
+        security.setAttributeNS(envelopeNs, `${prefix}:${actorAttribute(version)}`, config.actor);
+    }
+    else {
+        security.removeAttributeNS(envelopeNs, actorAttribute(version));
+    }
+    if (config.mustUnderstand) {
+        security.setAttributeNS(envelopeNs, `${prefix}:mustUnderstand`, mustUnderstandValue(version));
+    }
+    else {
+        security.removeAttributeNS(envelopeNs, 'mustUnderstand');
+    }
+    return security;
+}
+/** The password type an entry effectively uses, after the request-level override. */
+function effectivePasswordType(entry, override) {
+    // 'none' is a deliberate "send no password"; a request property never turns it back on.
+    return entry.passwordType === 'none' ? 'none' : (override ?? entry.passwordType);
+}
+/** Builds the element for one entry, resolving its secret through `ctx`. */
+async function buildEntry(entry, config, ctx, properties) {
+    if (entry.kind === 'timestamp') {
+        return buildTimestamp({
+            ttlSeconds: properties?.wssTimeToLive ?? entry.timeToLiveSeconds,
+            millisecondPrecision: entry.millisecondPrecision,
+            clock: ctx.clock,
+            uuid: ctx.uuid,
+        });
+    }
+    if (entry.kind === 'username-token') {
+        const passwordType = effectivePasswordType(entry, properties?.wssPasswordType);
+        const ref = entry.passwordRef ?? config.defaultPasswordRef;
+        const password = passwordType === 'none' || ref === undefined ? undefined : await ctx.secrets(ref);
+        return buildUsernameToken({
+            username: entry.username,
+            ...(password !== undefined ? { password } : {}),
+            passwordType,
+            addNonce: entry.addNonce,
+            addCreated: entry.addCreated,
+            clock: ctx.clock,
+            nonce: ctx.nonce,
+            uuid: ctx.uuid,
+        });
+    }
+    throw new WssError('wss-entry-unsupported', `WS-Security "${entry.kind}" entries are not supported yet.`, {
+        details: { kind: entry.kind },
+    });
+}
+/** Loads the keystore a signature or encryption entry names and picks its alias. */
+async function resolveKeystoreAlias(entry, config, ctx) {
+    const keystore = await ctx.keystores(entry.keystoreRef);
+    if (keystore === undefined) {
+        throw new WssError('wss-keystore-missing', 'The keystore this entry needs is not available.', {
+            details: { keystoreRef: entry.keystoreRef },
+        });
+    }
+    return {
+        keystore,
+        alias: selectAlias(keystore, entry.alias ?? config.defaultAlias),
+        ...(config.actor !== undefined ? { actor: config.actor } : {}),
+    };
+}
+/**
+ * Applies `config` to `envelopeXml`, returning the new envelope.
+ *
+ * The `soap:Header` is created (before the `Body`) when missing, the `wsse:Security` block
+ * addressed to `config.actor` is reused when one already exists, and the entries are appended
+ * to it in configuration order. Request-level `wssPasswordType`/`wssTimeToLive` override the
+ * matching entry fields for this application only.
+ *
+ * @param envelopeXml the envelope to secure
+ * @param config the outgoing configuration
+ * @param ctx the injected keystore/secret/clock/entropy capabilities
+ * @param options request-level property overrides
+ * @returns the serialized, secured envelope
+ * @throws WssError `wss-not-an-envelope`, or `wss-entry-unsupported` for an unknown entry kind
+ */
+export async function applyOutgoingWss(envelopeXml, config, ctx, options) {
+    const { doc, version } = parseEnvelope(envelopeXml);
+    for (const entry of config.entries) {
+        // The header is re-resolved every iteration because signing re-serializes the whole
+        // document (xml-crypto only speaks strings), which invalidates any element held across it.
+        const root = doc.documentElement;
+        if (root === null) {
+            throw new WssError('wss-not-an-envelope', 'WS-Security can only be applied to a SOAP envelope.');
+        }
+        const header = ensureHeader(doc, root, version);
+        const security = ensureSecurity(doc, root, header, version, config);
+        if (entry.kind === 'signature') {
+            await signEnvelope(doc, entry, await resolveKeystoreAlias(entry, config, ctx), ctx);
+            continue;
+        }
+        if (entry.kind === 'encryption') {
+            encryptEnvelope(doc, entry, await resolveKeystoreAlias(entry, config, ctx), ctx);
+            continue;
+        }
+        security.appendChild(doc.importNode(await buildEntry(entry, config, ctx, options?.requestProperties), true));
+    }
+    if (config.entries.length === 0) {
+        const root = doc.documentElement;
+        if (root !== null) {
+            ensureSecurity(doc, root, ensureHeader(doc, root, version), version, config);
+        }
+    }
+    return serializeXml(doc);
+}
+/**
+ * Removes the `wsse:Security` header addressed to `actor` (the ultimate receiver's when
+ * `actor` is omitted), plus the `soap:Header` if that emptied it.
+ *
+ * @param envelopeXml the envelope to clean
+ * @param actor the actor/role whose Security block to remove
+ * @returns the envelope without that header; unchanged when there is nothing to remove
+ */
+export function removeOutgoingWss(envelopeXml, actor) {
+    let parsed;
+    try {
+        parsed = parseEnvelope(envelopeXml);
+    }
+    catch {
+        return envelopeXml;
+    }
+    const { doc, root, version } = parsed;
+    const header = childElement(root, envelopeNamespace(version), 'Header');
+    if (header === undefined) {
+        return envelopeXml;
+    }
+    let removed = false;
+    for (const security of securityHeaders(header)) {
+        if (securityActor(security, version) === actor) {
+            header.removeChild(security);
+            removed = true;
+        }
+    }
+    if (!removed) {
+        return envelopeXml;
+    }
+    if (childElement(header, NS.WSSE, 'Security') === undefined && headerHasOnlyWhitespace(header)) {
+        root.removeChild(header);
+    }
+    return serializeXml(doc);
+}

package/dist/wss/c14n-prefixes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `InclusiveNamespaces PrefixList` exclusive canonicalization needs to be told about.
+ *
+ * Exclusive c14n's "visible utilization" rule only looks at element and attribute *names*, so a
+ * prefix a subtree uses only inside an attribute value or in text — `xsi:type="tns:Foo"`, a
+ * WSDL/XSD `ref`, a `QName` element body — loses its declaration and the canonical form stops
+ * meaning what it said. Both `outgoing/signature.ts` (per-reference transforms) and
+ * `outgoing/encryption.ts` (the plaintext it canonicalizes before encrypting) need the same
+ * list, so the rule lives here once.
+ */
+import type { Element } from '@xmldom/xmldom';
+/**
+ * The `InclusiveNamespaces PrefixList` exclusive c14n of `element` needs: every prefix
+ * `element`'s subtree references only through attribute-value or text QName content — a use
+ * exclusive c14n's "visible utilization" rule does not see — plus `envelopePrefix` when one is
+ * given.
+ *
+ * A prefix `element` already declares on itself is left out: exclusive c14n renders that
+ * declaration regardless, so listing it again would be redundant, not wrong.
+ *
+ * @param element the element about to be canonicalized
+ * @param envelopePrefix the SOAP envelope's own prefix when the canonical form has to stand on
+ *   its own inside the envelope (a signature reference), or `null` when it does not (an
+ *   encrypted plaintext, which is self-contained by construction)
+ * @returns the prefixes to list, sorted, so the value is stable
+ */
+export declare function inclusiveNamespacePrefixList(element: Element, envelopePrefix: string | null): string[];