@wirebench/engine 2.1.1

package/dist/wss/outgoing/signature.d.ts

@@ -0,0 +1,73 @@
+/**
+ * XML Signature for an outgoing WS-Security header, on top of `xml-crypto`'s `SignedXml`.
+ *
+ * `xml-crypto` only speaks serialized XML: it parses the string it is given, adds the
+ * `<ds:Signature>` and hands back a new string. {@link signEnvelope} therefore serializes the
+ * document it is given, signs, re-parses and swaps the result into the *same* `Document`
+ * object — so the caller's reference stays valid, at the cost of every `Element` it held
+ * before the call becoming stale. `applyOutgoingWss` re-resolves the `wsse:Security` block
+ * after each signature entry for exactly that reason.
+ */
+import type { Document } from '@xmldom/xmldom';
+import type { Keystore, KeystoreAlias } from '../keystore/model.js';
+import type { WssContext, WssSignatureEntry } from '../model.js';
+/** The keystore material {@link signEnvelope} signs with, resolved by the caller. */
+export interface ResolvedSigningKey {
+    readonly keystore: Keystore;
+    readonly alias: KeystoreAlias;
+    /** The actor/role of the `wsse:Security` block the signature belongs in. */
+    readonly actor?: string;
+}
+/** The outcome of {@link verifySignature}. */
+export interface VerifySignatureResult {
+    readonly ok: boolean;
+    /** The `URI`s the signature's references pointed at, without their leading `#`. */
+    readonly references: readonly string[];
+    /** Why verification failed; absent when `ok`. */
+    readonly error?: string;
+}
+/** What {@link verifySignature} needs to check a signature. */
+export interface VerifySignatureOptions {
+    /** The signer's certificate, PEM encoded. */
+    readonly certPem: string;
+    /**
+     * Which `ds:Signature` to verify, when `xml` carries more than one. `index` counts among every
+     * `ds:Signature` element in the document, in document order (depth-first, pre-order) — the
+     * same order {@link findAllSignatures} and `verifyIncoming`'s own signature list use, so the
+     * two never disagree about which signature `index` names. Defaults to `0` (the first).
+     *
+     * Selecting by index against the *unmodified* document — rather than stripping every other
+     * `ds:Signature` before verifying — matters because a genuine signature's own references can
+     * cover the `wsse:Security` header (an enveloped-signature transform over a header that holds
+     * a second signature): removing that second signature before verification would change the
+     * bytes the first signature's digest was computed over, and it would fail.
+     */
+    readonly signature?: {
+        readonly index: number;
+    };
+}
+/**
+ * Signs the parts `entry` names and appends the `<ds:Signature>` to the `wsse:Security` block
+ * addressed to `resolved.actor`, mutating `doc` in place.
+ *
+ * Every referenced part is given a `wsu:Id="Id-<uuid>"` first (existing ids are kept), so the
+ * references are stable and `xml-crypto` never has to invent one.
+ *
+ * @param doc the envelope, already carrying its `wsse:Security` header
+ * @param entry the signature configuration
+ * @param resolved the keystore alias to sign with, and the Security block's actor
+ * @param ctx the injected secret/uuid capabilities
+ * @throws WssError `wss-not-an-envelope`, `wss-part-missing`, `wss-ski-missing`, `wss-signing-key-missing`
+ */
+export declare function signEnvelope(doc: Document, entry: WssSignatureEntry, resolved: ResolvedSigningKey, ctx: WssContext): Promise<void>;
+/**
+ * Verifies the `ds:Signature` in `xml` against `certPem`.
+ *
+ * The certificate is supplied by the caller rather than taken from the document's own
+ * `KeyInfo`: a signature is only meaningful against a key you already trust.
+ *
+ * @param xml the signed envelope
+ * @param options the certificate to verify against
+ * @returns whether the signature held, and which references it covered
+ */
+export declare function verifySignature(xml: string, options: VerifySignatureOptions): VerifySignatureResult;

package/dist/wss/outgoing/signature.js

@@ -0,0 +1,239 @@
+/**
+ * XML Signature for an outgoing WS-Security header, on top of `xml-crypto`'s `SignedXml`.
+ *
+ * `xml-crypto` only speaks serialized XML: it parses the string it is given, adds the
+ * `<ds:Signature>` and hands back a new string. {@link signEnvelope} therefore serializes the
+ * document it is given, signs, re-parses and swaps the result into the *same* `Document`
+ * object — so the caller's reference stays valid, at the cost of every `Element` it held
+ * before the call becoming stale. `applyOutgoingWss` re-resolves the `wsse:Security` block
+ * after each signature entry for exactly that reason.
+ */
+import { createPrivateKey } from 'node:crypto';
+import { SignedXml } from 'xml-crypto';
+import { WssError } from '../../errors.js';
+import { NS } from '../../xml/namespaces.js';
+import { parseXml } from '../../xml/parse.js';
+import { serializeXml } from '../../xml/serialize.js';
+import { detectEnvelopeVersion, envelopeNamespace } from '../../soap/envelope.js';
+import { buildKeyIdentifier } from '../key-identifiers.js';
+import { inclusiveNamespacePrefixList } from '../c14n-prefixes.js';
+import { childElement, findElement, securityIndex } from '../security-header.js';
+/** Exclusive XML canonicalization, the only form this build emits. */
+const EXC_C14N = 'http://www.w3.org/2001/10/xml-exc-c14n#';
+/** `SignatureMethod` URIs, by the entry's `signatureAlgorithm`. */
+const SIGNATURE_ALGORITHM_URIS = {
+    'rsa-sha256': 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
+    'rsa-sha1': 'http://www.w3.org/2000/09/xmldsig#rsa-sha1',
+};
+/** `DigestMethod` URIs, by the entry's `digestAlgorithm`. */
+const DIGEST_ALGORITHM_URIS = {
+    sha256: 'http://www.w3.org/2001/04/xmlenc#sha256',
+    sha1: 'http://www.w3.org/2000/09/xmldsig#sha1',
+};
+/** True when `element` already carries a `wsu:Id`. */
+function existingWsuId(element) {
+    const value = element.getAttributeNS(NS.WSU, 'Id');
+    return value === null || value === '' ? undefined : value;
+}
+/**
+ * The element a part names. The two SOAP envelope namespaces are treated as one so the default
+ * parts (which store the SOAP 1.1 namespace for `Body`) also match a SOAP 1.2 envelope.
+ */
+function resolvePart(root, part, envelopeNs) {
+    const namespace = part.namespace === NS.SOAP11_ENV || part.namespace === NS.SOAP12_ENV ? envelopeNs : part.namespace;
+    return findElement(root, namespace, part.name);
+}
+/** The private key of `alias`, decrypted with `passphrase` when its PEM needs one. */
+function privateKeyOf(alias, passphrase) {
+    const keyPem = alias.keyPem;
+    if (keyPem === undefined || keyPem === '') {
+        throw new WssError('wss-signing-key-missing', `Keystore alias "${alias.alias}" has no private key to sign with.`);
+    }
+    try {
+        return createPrivateKey(keyPem);
+    }
+    catch (cause) {
+        if (passphrase === undefined) {
+            throw new WssError('wss-signing-key-missing', 'The signing key could not be read.', { cause });
+        }
+        try {
+            return createPrivateKey({ key: keyPem, passphrase });
+        }
+        catch (innerCause) {
+            throw new WssError('wss-signing-key-missing', 'The signing key could not be decrypted.', { cause: innerCause });
+        }
+    }
+}
+/**
+ * Signs the parts `entry` names and appends the `<ds:Signature>` to the `wsse:Security` block
+ * addressed to `resolved.actor`, mutating `doc` in place.
+ *
+ * Every referenced part is given a `wsu:Id="Id-<uuid>"` first (existing ids are kept), so the
+ * references are stable and `xml-crypto` never has to invent one.
+ *
+ * @param doc the envelope, already carrying its `wsse:Security` header
+ * @param entry the signature configuration
+ * @param resolved the keystore alias to sign with, and the Security block's actor
+ * @param ctx the injected secret/uuid capabilities
+ * @throws WssError `wss-not-an-envelope`, `wss-part-missing`, `wss-ski-missing`, `wss-signing-key-missing`
+ */
+export async function signEnvelope(doc, entry, resolved, ctx) {
+    const root = doc.documentElement;
+    const version = detectEnvelopeVersion(doc);
+    if (root === null || version === undefined) {
+        throw new WssError('wss-not-an-envelope', 'WS-Security can only be applied to a SOAP envelope.');
+    }
+    const envelopeNs = envelopeNamespace(version);
+    const header = childElement(root, envelopeNs, 'Header');
+    const security = header === undefined ? undefined : findElement(header, NS.WSSE, 'Security');
+    if (header === undefined || security === undefined) {
+        throw new WssError('wss-not-an-envelope', 'The envelope has no wsse:Security header to sign into.');
+    }
+    const references = [];
+    for (const part of entry.parts) {
+        const element = resolvePart(root, part, envelopeNs);
+        if (element === undefined) {
+            throw new WssError('wss-part-missing', `The message has no "${part.name}" element to sign.`, {
+                details: { name: part.name, namespace: part.namespace },
+            });
+        }
+        let id = existingWsuId(element);
+        if (id === undefined) {
+            id = `Id-${ctx.uuid()}`;
+            // Only declare `xmlns:wsu` here when no ancestor already binds the prefix to the WS-Utility
+            // namespace (the `wsse:Security` block does, for every part it added itself) — redeclaring
+            // it lower down is harmless to a parser but noise `verifySignature`/`xmlsec1` never asked for.
+            if (element.lookupNamespaceURI('wsu') !== NS.WSU) {
+                element.setAttributeNS('http://www.w3.org/2000/xmlns/', 'xmlns:wsu', NS.WSU);
+            }
+            element.setAttributeNS(NS.WSU, 'wsu:Id', id);
+        }
+        references.push({ id, element });
+    }
+    const keyIdentifier = buildKeyIdentifier(entry.keyIdentifierType, {
+        certPem: resolved.alias.certPem,
+        chainPem: resolved.alias.chainPem,
+        useSingleCertificate: entry.useSingleCertificate,
+        tokenId: `X509-${ctx.uuid()}`,
+    });
+    if (keyIdentifier.binarySecurityTokenXml !== undefined) {
+        const token = parseXml(keyIdentifier.binarySecurityTokenXml, { location: 'envelope' }).documentElement;
+        if (token !== null) {
+            security.appendChild(doc.importNode(token, true));
+        }
+    }
+    const passphrase = entry.keyPasswordRef === undefined ? undefined : await ctx.secrets(entry.keyPasswordRef);
+    // The envelope's own prefix, needed on the SignedInfo canonicalization itself and on every
+    // reference transform: exclusive c14n only renders a namespace declaration a part visibly
+    // uses on an element/attribute *name*, so a receiver that canonicalizes a reference on its
+    // own (rather than trusting this build's canonical form) needs it spelled out.
+    const envPrefix = root.prefix;
+    const signer = new SignedXml({
+        idMode: 'wssecurity',
+        privateKey: privateKeyOf(resolved.alias, passphrase),
+        publicCert: resolved.alias.certPem,
+        canonicalizationAlgorithm: EXC_C14N,
+        inclusiveNamespacesPrefixList: envPrefix !== null && envPrefix !== '' ? [envPrefix] : [],
+        signatureAlgorithm: SIGNATURE_ALGORITHM_URIS[entry.signatureAlgorithm],
+        getKeyInfoContent: () => keyIdentifier.keyInfoXml,
+    });
+    for (const { id, element } of references) {
+        signer.addReference({
+            // By id rather than by element name: the id is unique, so this selects exactly the one
+            // element even when the envelope carries two parts with the same local name.
+            xpath: `//*[@*[local-name(.)='Id']='${id}']`,
+            transforms: [EXC_C14N],
+            digestAlgorithm: DIGEST_ALGORITHM_URIS[entry.digestAlgorithm],
+            inclusiveNamespacesPrefixList: inclusiveNamespacePrefixList(element, envPrefix),
+        });
+    }
+    // The index and the XPath must count the same node set — direct `wsse:Security` children of
+    // the header — so a `wsse:Security` nested elsewhere (inside the Body, say) never shifts
+    // which block xml-crypto appends the signature into. `securityIndex` throws when no direct
+    // child matches, so `index` is never used to build an XPath that resolves to nothing.
+    const index = securityIndex(header, version, resolved.actor);
+    signer.computeSignature(serializeXml(doc), {
+        prefix: 'ds',
+        location: {
+            reference: `/*[local-name()='Envelope']/*[local-name()='Header']` +
+                `/*[local-name()='Security' and namespace-uri()='${NS.WSSE}'][${index}]`,
+            action: 'append',
+        },
+    });
+    const signed = parseXml(signer.getSignedXml(), { location: 'envelope' });
+    const next = signed.documentElement;
+    if (next !== null) {
+        doc.replaceChild(doc.importNode(next, true), root);
+    }
+}
+/** Every `ds:Signature` element under `root`, in document order (depth-first, pre-order). */
+function findAllSignatures(root) {
+    const found = [];
+    const walk = (node) => {
+        if (node.namespaceURI === NS.DS && node.localName === 'Signature') {
+            found.push(node);
+        }
+        for (let child = node.firstChild; child !== null; child = child.nextSibling) {
+            if (child.nodeType === 1) {
+                walk(child);
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+/** The `URI`s of a signature's `ds:Reference` children, without their leading `#`. */
+function referenceUris(signature) {
+    const signedInfo = childElement(signature, NS.DS, 'SignedInfo');
+    if (signedInfo === undefined) {
+        return [];
+    }
+    const uris = [];
+    for (let node = signedInfo.firstChild; node !== null; node = node.nextSibling) {
+        const element = node;
+        if (element.nodeType === 1 && element.namespaceURI === NS.DS && element.localName === 'Reference') {
+            const uri = element.getAttribute('URI') ?? '';
+            uris.push(uri.startsWith('#') ? uri.slice(1) : uri);
+        }
+    }
+    return uris;
+}
+/**
+ * Verifies the `ds:Signature` in `xml` against `certPem`.
+ *
+ * The certificate is supplied by the caller rather than taken from the document's own
+ * `KeyInfo`: a signature is only meaningful against a key you already trust.
+ *
+ * @param xml the signed envelope
+ * @param options the certificate to verify against
+ * @returns whether the signature held, and which references it covered
+ */
+export function verifySignature(xml, options) {
+    let signature;
+    try {
+        const root = parseXml(xml, { location: 'envelope' }).documentElement;
+        const signatures = root === null ? [] : findAllSignatures(root);
+        signature = signatures[options.signature?.index ?? 0];
+    }
+    catch (error) {
+        return { ok: false, references: [], error: error instanceof Error ? error.message : String(error) };
+    }
+    if (signature === undefined) {
+        return { ok: false, references: [], error: 'The document carries no ds:Signature element.' };
+    }
+    const references = referenceUris(signature);
+    const verifier = new SignedXml({
+        idMode: 'wssecurity',
+        publicCert: options.certPem,
+        // Trust the caller's certificate, never the one the document brought with it.
+        getCertFromKeyInfo: () => null,
+    });
+    try {
+        verifier.loadSignature(serializeXml(signature));
+        const ok = verifier.checkSignature(xml);
+        return ok ? { ok, references } : { ok, references, error: 'One or more references failed validation.' };
+    }
+    catch (error) {
+        return { ok: false, references, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/wss/outgoing/timestamp.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Builds the `wsu:Timestamp` element of an outgoing WS-Security header
+ * (WS-Security 1.0 utility schema).
+ */
+import type { Element } from '@xmldom/xmldom';
+/** What {@link buildTimestamp} needs. All time and identity comes in; nothing is read here. */
+export interface BuildTimestampInput {
+    /** Seconds between `Created` and `Expires`; `0` (or less) omits `Expires`. */
+    readonly ttlSeconds: number;
+    /** Emit `.SSS` fractional seconds rather than whole seconds. */
+    readonly millisecondPrecision: boolean;
+    readonly clock: () => Date;
+    readonly uuid: () => string;
+}
+/**
+ * Formats `date` as an XSD `dateTime` in UTC, with or without milliseconds.
+ *
+ * @param date the instant to format
+ * @param millisecondPrecision include `.SSS`
+ * @returns e.g. `2026-09-09T12:00:00Z` or `2026-09-09T12:00:00.250Z`
+ */
+export declare function formatWssDateTime(date: Date, millisecondPrecision: boolean): string;
+/**
+ * Builds `<wsu:Timestamp wsu:Id="TS-…"><wsu:Created/>[<wsu:Expires/>]</wsu:Timestamp>`.
+ *
+ * @param input the TTL, precision and the injected clock/uuid
+ * @returns a detached element owned by a fresh document
+ */
+export declare function buildTimestamp(input: BuildTimestampInput): Element;

package/dist/wss/outgoing/timestamp.js

@@ -0,0 +1,39 @@
+/**
+ * Builds the `wsu:Timestamp` element of an outgoing WS-Security header
+ * (WS-Security 1.0 utility schema).
+ */
+import { DOMImplementation } from '@xmldom/xmldom';
+import { NS } from '../../xml/namespaces.js';
+/**
+ * Formats `date` as an XSD `dateTime` in UTC, with or without milliseconds.
+ *
+ * @param date the instant to format
+ * @param millisecondPrecision include `.SSS`
+ * @returns e.g. `2026-09-09T12:00:00Z` or `2026-09-09T12:00:00.250Z`
+ */
+export function formatWssDateTime(date, millisecondPrecision) {
+    const iso = date.toISOString();
+    return millisecondPrecision ? iso : `${iso.slice(0, 19)}Z`;
+}
+/**
+ * Builds `<wsu:Timestamp wsu:Id="TS-…"><wsu:Created/>[<wsu:Expires/>]</wsu:Timestamp>`.
+ *
+ * @param input the TTL, precision and the injected clock/uuid
+ * @returns a detached element owned by a fresh document
+ */
+export function buildTimestamp(input) {
+    const doc = new DOMImplementation().createDocument(null, '', null);
+    const timestamp = doc.createElementNS(NS.WSU, 'wsu:Timestamp');
+    timestamp.setAttributeNS(NS.WSU, 'wsu:Id', `TS-${input.uuid()}`);
+    const created = input.clock();
+    const createdElement = doc.createElementNS(NS.WSU, 'wsu:Created');
+    createdElement.appendChild(doc.createTextNode(formatWssDateTime(created, input.millisecondPrecision)));
+    timestamp.appendChild(createdElement);
+    if (input.ttlSeconds > 0) {
+        const expiresElement = doc.createElementNS(NS.WSU, 'wsu:Expires');
+        const expires = new Date(created.getTime() + input.ttlSeconds * 1000);
+        expiresElement.appendChild(doc.createTextNode(formatWssDateTime(expires, input.millisecondPrecision)));
+        timestamp.appendChild(expiresElement);
+    }
+    return timestamp;
+}

package/dist/wss/outgoing/username-token.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Builds the `wsse:UsernameToken` element of an outgoing WS-Security header
+ * (WS-Security UsernameToken Profile 1.0).
+ */
+import type { Element } from '@xmldom/xmldom';
+import type { WssPasswordType } from '../model.js';
+/** What {@link buildUsernameToken} needs; the password is already resolved by the host. */
+export interface BuildUsernameTokenInput {
+    readonly username: string;
+    /** The resolved plaintext password; absent is treated as empty. */
+    readonly password?: string;
+    readonly passwordType: WssPasswordType;
+    readonly addNonce: boolean;
+    readonly addCreated: boolean;
+    readonly clock: () => Date;
+    readonly nonce: (bytes: number) => Uint8Array;
+    readonly uuid: () => string;
+}
+/**
+ * `Base64(SHA-1(nonce ‖ created ‖ password))`, the profile's `PasswordDigest`.
+ *
+ * @param nonce the raw nonce bytes (not their Base64 form)
+ * @param created the `wsu:Created` text, byte-for-byte as it appears in the token
+ * @param password the plaintext password
+ * @returns the Base64 digest
+ */
+export declare function passwordDigest(nonce: Uint8Array, created: string, password: string): string;
+/**
+ * Builds `<wsse:UsernameToken wsu:Id="UsernameToken-…">` with the username, an optional
+ * password (text or digest), and an optional nonce/created pair. `PasswordDigest` forces the
+ * nonce and created on, since the digest is not verifiable without them.
+ *
+ * @param input the credentials, the password type and the injected clock/nonce/uuid
+ * @returns a detached element owned by a fresh document
+ */
+export declare function buildUsernameToken(input: BuildUsernameTokenInput): Element;

package/dist/wss/outgoing/username-token.js

@@ -0,0 +1,68 @@
+/**
+ * Builds the `wsse:UsernameToken` element of an outgoing WS-Security header
+ * (WS-Security UsernameToken Profile 1.0).
+ */
+import { createHash } from 'node:crypto';
+import { DOMImplementation } from '@xmldom/xmldom';
+import { NS } from '../../xml/namespaces.js';
+import { formatWssDateTime } from './timestamp.js';
+/** `Type` attribute values of `wsse:Password`. */
+const PROFILE = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0';
+/** `EncodingType` of `wsse:Nonce`. */
+const BASE64_BINARY = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary';
+/** Nonce length the profile's examples use, and what every interoperable stack expects. */
+const NONCE_BYTES = 16;
+/**
+ * `Base64(SHA-1(nonce ‖ created ‖ password))`, the profile's `PasswordDigest`.
+ *
+ * @param nonce the raw nonce bytes (not their Base64 form)
+ * @param created the `wsu:Created` text, byte-for-byte as it appears in the token
+ * @param password the plaintext password
+ * @returns the Base64 digest
+ */
+export function passwordDigest(nonce, created, password) {
+    return createHash('sha1')
+        .update(Buffer.concat([Buffer.from(nonce), Buffer.from(created, 'utf8'), Buffer.from(password, 'utf8')]))
+        .digest('base64');
+}
+/**
+ * Builds `<wsse:UsernameToken wsu:Id="UsernameToken-…">` with the username, an optional
+ * password (text or digest), and an optional nonce/created pair. `PasswordDigest` forces the
+ * nonce and created on, since the digest is not verifiable without them.
+ *
+ * @param input the credentials, the password type and the injected clock/nonce/uuid
+ * @returns a detached element owned by a fresh document
+ */
+export function buildUsernameToken(input) {
+    const digest = input.passwordType === 'digest';
+    const withNonce = input.addNonce || digest;
+    const withCreated = input.addCreated || digest;
+    const nonceBytes = withNonce ? input.nonce(NONCE_BYTES) : undefined;
+    const created = withCreated ? formatWssDateTime(input.clock(), false) : undefined;
+    const doc = new DOMImplementation().createDocument(null, '', null);
+    const token = doc.createElementNS(NS.WSSE, 'wsse:UsernameToken');
+    token.setAttributeNS(NS.WSU, 'wsu:Id', `UsernameToken-${input.uuid()}`);
+    const append = (namespace, name, text) => {
+        const element = doc.createElementNS(namespace, name);
+        if (text !== undefined && text !== '') {
+            element.appendChild(doc.createTextNode(text));
+        }
+        token.appendChild(element);
+        return element;
+    };
+    append(NS.WSSE, 'wsse:Username', input.username);
+    if (input.passwordType !== 'none') {
+        const password = input.password ?? '';
+        const value = digest ? passwordDigest(nonceBytes ?? new Uint8Array(), created ?? '', password) : password;
+        const element = append(NS.WSSE, 'wsse:Password', value);
+        element.setAttribute('Type', `${PROFILE}#${digest ? 'PasswordDigest' : 'PasswordText'}`);
+    }
+    if (nonceBytes !== undefined) {
+        const element = append(NS.WSSE, 'wsse:Nonce', Buffer.from(nonceBytes).toString('base64'));
+        element.setAttribute('EncodingType', BASE64_BINARY);
+    }
+    if (created !== undefined) {
+        append(NS.WSU, 'wsu:Created', created);
+    }
+    return token;
+}

package/dist/wss/security-header.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Locating the pieces of a secured envelope: the `soap:Header`, the `wsse:Security` block
+ * addressed to a given actor/role, and arbitrary elements named by `{namespace, localName}`.
+ * Shared by `apply.ts` (which builds the header) and `outgoing/signature.ts` (which has to find
+ * it again after `xml-crypto` has re-serialized the document).
+ */
+import type { Document, Element } from '@xmldom/xmldom';
+import type { SoapEnvelopeVersion } from '../soap/envelope.js';
+/** The attribute name carrying the SOAP actor/role for `version`. */
+export declare function actorAttribute(version: SoapEnvelopeVersion): string;
+/** The `mustUnderstand` value `version` expects. */
+export declare function mustUnderstandValue(version: SoapEnvelopeVersion): string;
+/** The first child element of `parent` in `namespace` with local name `localName`. */
+export declare function childElement(parent: Element, namespace: string, localName: string): Element | undefined;
+/** Every `wsse:Security` header block in `header`, in document order. */
+export declare function securityHeaders(header: Element): Element[];
+/** The actor/role a `wsse:Security` element is addressed to, or `undefined` for the ultimate receiver. */
+export declare function securityActor(security: Element, version: SoapEnvelopeVersion): string | undefined;
+/**
+ * The index (1-based, as XPath counts) of the `wsse:Security` block addressed to `actor`,
+ * among `header`'s direct `wsse:Security` children — the same node set the XPath
+ * `signEnvelope` hands `xml-crypto` selects, so the two never disagree about which block is
+ * "the" one to sign into.
+ *
+ * @throws WssError `wss-security-missing` when no direct child is addressed to `actor`
+ */
+export declare function securityIndex(header: Element, version: SoapEnvelopeVersion, actor?: string): number;
+/** The first descendant-or-self of `root` in `namespace` with local name `localName`. */
+export declare function findElement(root: Element, namespace: string, localName: string): Element | undefined;
+/** Replaces `doc`'s document element with `replacement`'s, so callers holding `doc` stay valid. */
+export declare function replaceDocumentElement(doc: Document, replacement: Document): void;

package/dist/wss/security-header.js

@@ -0,0 +1,83 @@
+/**
+ * Locating the pieces of a secured envelope: the `soap:Header`, the `wsse:Security` block
+ * addressed to a given actor/role, and arbitrary elements named by `{namespace, localName}`.
+ * Shared by `apply.ts` (which builds the header) and `outgoing/signature.ts` (which has to find
+ * it again after `xml-crypto` has re-serialized the document).
+ */
+import { WssError } from '../errors.js';
+import { NS } from '../xml/namespaces.js';
+import { envelopeNamespace } from '../soap/envelope.js';
+/** The attribute name carrying the SOAP actor/role for `version`. */
+export function actorAttribute(version) {
+    return version === '1.2' ? 'role' : 'actor';
+}
+/** The `mustUnderstand` value `version` expects. */
+export function mustUnderstandValue(version) {
+    return version === '1.2' ? 'true' : '1';
+}
+/** The first child element of `parent` in `namespace` with local name `localName`. */
+export function childElement(parent, namespace, localName) {
+    for (let node = parent.firstChild; node !== null; node = node.nextSibling) {
+        const element = node;
+        if (element.nodeType === 1 && element.namespaceURI === namespace && element.localName === localName) {
+            return element;
+        }
+    }
+    return undefined;
+}
+/** Every `wsse:Security` header block in `header`, in document order. */
+export function securityHeaders(header) {
+    const found = [];
+    for (let node = header.firstChild; node !== null; node = node.nextSibling) {
+        const element = node;
+        if (element.nodeType === 1 && element.namespaceURI === NS.WSSE && element.localName === 'Security') {
+            found.push(element);
+        }
+    }
+    return found;
+}
+/** The actor/role a `wsse:Security` element is addressed to, or `undefined` for the ultimate receiver. */
+export function securityActor(security, version) {
+    const value = security.getAttributeNS(envelopeNamespace(version), actorAttribute(version));
+    return value === null || value === '' ? undefined : value;
+}
+/**
+ * The index (1-based, as XPath counts) of the `wsse:Security` block addressed to `actor`,
+ * among `header`'s direct `wsse:Security` children — the same node set the XPath
+ * `signEnvelope` hands `xml-crypto` selects, so the two never disagree about which block is
+ * "the" one to sign into.
+ *
+ * @throws WssError `wss-security-missing` when no direct child is addressed to `actor`
+ */
+export function securityIndex(header, version, actor) {
+    const index = securityHeaders(header).findIndex((element) => securityActor(element, version) === actor);
+    if (index === -1) {
+        throw new WssError('wss-security-missing', 'The envelope has no wsse:Security header addressed to the expected actor/role.');
+    }
+    return index + 1;
+}
+/** The first descendant-or-self of `root` in `namespace` with local name `localName`. */
+export function findElement(root, namespace, localName) {
+    if (root.namespaceURI === namespace && root.localName === localName) {
+        return root;
+    }
+    for (let node = root.firstChild; node !== null; node = node.nextSibling) {
+        if (node.nodeType !== 1) {
+            continue;
+        }
+        const found = findElement(node, namespace, localName);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}
+/** Replaces `doc`'s document element with `replacement`'s, so callers holding `doc` stay valid. */
+export function replaceDocumentElement(doc, replacement) {
+    const current = doc.documentElement;
+    const next = replacement.documentElement;
+    if (current === null || next === null) {
+        return;
+    }
+    doc.replaceChild(doc.importNode(next, true), current);
+}

package/dist/xml/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Browser-safe subpath export (`@wirebench/engine/xml`): pure text helpers
+ * with no dependency on `@xmldom/xmldom` or any Node module, safe to bundle
+ * into the Electron renderer.
+ */
+export { formatXml, type FormatXmlOptions, type FormatXmlResult } from './pretty.js';
+export { elementPathAt, completionContextAt, type CompletionContext, type TextRange } from '../xsd/locate.js';

package/dist/xml/index.js

@@ -0,0 +1,7 @@
+/**
+ * Browser-safe subpath export (`@wirebench/engine/xml`): pure text helpers
+ * with no dependency on `@xmldom/xmldom` or any Node module, safe to bundle
+ * into the Electron renderer.
+ */
+export { formatXml } from './pretty.js';
+export { elementPathAt, completionContextAt } from '../xsd/locate.js';

package/dist/xml/namespaces.d.ts

@@ -0,0 +1,36 @@
+/**
+ * XML namespace URIs used across WSDL, SOAP, XSD, WS-Security, WS-Addressing
+ * and WS-Policy. Centralizing these avoids typos scattered through the
+ * codebase and gives every consumer the same canonical values.
+ */
+export declare const NS: {
+    readonly WSDL: "http://schemas.xmlsoap.org/wsdl/";
+    readonly WSDL_SOAP11: "http://schemas.xmlsoap.org/wsdl/soap/";
+    readonly WSDL_SOAP12: "http://schemas.xmlsoap.org/wsdl/soap12/";
+    readonly WSDL_HTTP: "http://schemas.xmlsoap.org/wsdl/http/";
+    readonly WSDL_MIME: "http://schemas.xmlsoap.org/wsdl/mime/";
+    readonly SOAP11_ENV: "http://schemas.xmlsoap.org/soap/envelope/";
+    readonly SOAP11_ENC: "http://schemas.xmlsoap.org/soap/encoding/";
+    readonly SOAP12_ENV: "http://www.w3.org/2003/05/soap-envelope";
+    readonly SOAP12_ENC: "http://www.w3.org/2003/05/soap-encoding";
+    readonly XSD: "http://www.w3.org/2001/XMLSchema";
+    readonly XSI: "http://www.w3.org/2001/XMLSchema-instance";
+    readonly XML: "http://www.w3.org/XML/1998/namespace";
+    readonly XOP: "http://www.w3.org/2004/08/xop/include";
+    readonly XMLMIME: "http://www.w3.org/2005/05/xmlmime";
+    readonly WSSE: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd";
+    readonly WSU: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";
+    readonly DS: "http://www.w3.org/2000/09/xmldsig#";
+    readonly XENC: "http://www.w3.org/2001/04/xmlenc#";
+    readonly WSA_200508: "http://www.w3.org/2005/08/addressing";
+    readonly WSA_200408: "http://schemas.xmlsoap.org/ws/2004/08/addressing";
+    readonly WSAW: "http://www.w3.org/2006/05/addressing/wsdl";
+    readonly WSAM: "http://www.w3.org/2007/05/addressing/metadata";
+    readonly WSAP_2004: "http://schemas.xmlsoap.org/ws/2004/08/addressing/policy";
+    readonly WSP: "http://www.w3.org/ns/ws-policy";
+    readonly WSP_2004: "http://schemas.xmlsoap.org/ws/2004/09/policy";
+};
+/** Union of every namespace URI known to {@link NS}. */
+export type NamespaceUri = (typeof NS)[keyof typeof NS];
+/** Conventional XML prefix for each namespace in {@link NS}. */
+export declare const PREFIX: Record<keyof typeof NS, string>;