@wirebench/engine 2.1.1

package/dist/wss/c14n-prefixes.js

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+/** The namespace `xmlns:*` declarations themselves live in. */
+const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
+/**
+ * Matches a `prefix:localName`-shaped token, the way a QName looks when it appears as an
+ * attribute value or as element text (`xsi:type="tns:Foo"`, a WSDL/XSD `ref` value, and so on).
+ */
+const QNAME_TOKEN = /\b([A-Za-z_][\w.-]*):[A-Za-z_][\w.-]*/g;
+/** The prefixes `element` declares on itself via `xmlns:*` attributes. */
+function ownDeclaredPrefixes(element) {
+    const declared = new Set();
+    const attributes = element.attributes;
+    for (let i = 0; i < attributes.length; i += 1) {
+        const attribute = attributes.item(i);
+        if (attribute !== null &&
+            attribute.namespaceURI === XMLNS_NS &&
+            attribute.prefix === 'xmlns' &&
+            attribute.localName !== null) {
+            declared.add(attribute.localName);
+        }
+    }
+    return declared;
+}
+/** Every `prefix:local` token found in attribute values or text content under `element`. */
+function qnamePrefixesIn(element) {
+    const found = new Set();
+    const scan = (text) => {
+        QNAME_TOKEN.lastIndex = 0;
+        let match = QNAME_TOKEN.exec(text);
+        while (match !== null) {
+            const prefix = match[1];
+            if (prefix !== undefined) {
+                found.add(prefix);
+            }
+            match = QNAME_TOKEN.exec(text);
+        }
+    };
+    const walk = (node) => {
+        if (node.nodeType === 1) {
+            const el = node;
+            const attributes = el.attributes;
+            for (let i = 0; i < attributes.length; i += 1) {
+                const attribute = attributes.item(i);
+                if (attribute !== null && attribute.namespaceURI !== XMLNS_NS) {
+                    scan(attribute.value);
+                }
+            }
+            for (let child = el.firstChild; child !== null; child = child.nextSibling) {
+                walk(child);
+            }
+        }
+        else if (node.nodeType === 3) {
+            scan(node.nodeValue ?? '');
+        }
+    };
+    walk(element);
+    return found;
+}
+/**
+ * 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 function inclusiveNamespacePrefixList(element, envelopePrefix) {
+    const declared = ownDeclaredPrefixes(element);
+    const prefixes = new Set();
+    if (envelopePrefix !== null && envelopePrefix !== '') {
+        prefixes.add(envelopePrefix);
+    }
+    for (const prefix of qnamePrefixesIn(element)) {
+        if (!declared.has(prefix) && element.lookupNamespaceURI(prefix) !== null) {
+            prefixes.add(prefix);
+        }
+    }
+    return [...prefixes].sort();
+}

package/dist/wss/incoming/decrypt.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Decryption of an *incoming* message: the thin layer between a resolved keystore alias and
+ * Task 39's {@link decryptEnvelope}.
+ *
+ * The only behaviour it adds is the no-op: a response that carries neither an
+ * `xenc:EncryptedKey` nor an `xenc:EncryptedData` is not an error — it is simply a response
+ * that was not encrypted — so the caller gets the document back unchanged rather than a
+ * `wss-decrypt-failed` it would have to special-case.
+ */
+import type { Keystore, KeystoreAlias } from '../keystore/model.js';
+/** The keystore material {@link decryptIncoming} opens an `xenc:EncryptedKey` with. */
+export interface ResolvedDecryptionKey {
+    readonly keystore: Keystore;
+    /** The alias whose private key unwraps the symmetric key. */
+    readonly alias: KeystoreAlias;
+    /** Passphrase for an encrypted private key PEM. Resolved by the host; never logged. */
+    readonly keyPassword?: string;
+}
+/** The outcome of {@link decryptIncoming}. */
+export interface DecryptIncomingResult {
+    /** The message with every block this key could open restored; the input when there was none. */
+    readonly xml: string;
+    /** The plaintext of each decrypted block, in `ReferenceList` order. Empty for a no-op. */
+    readonly decrypted: readonly string[];
+}
+/**
+ * Decrypts an incoming message with `resolved`, or returns it untouched when it carries no
+ * XML-Encryption at all.
+ *
+ * @param xml the response envelope
+ * @param resolved the keystore alias (and passphrase) to decrypt with
+ * @returns the restored envelope and the plaintext of each decrypted block
+ * @throws WssError `wss-decrypt-failed`, `wss-algorithm-unsupported`, `wss-decryption-key-missing`
+ */
+export declare function decryptIncoming(xml: string, resolved: ResolvedDecryptionKey): DecryptIncomingResult;

package/dist/wss/incoming/decrypt.js

@@ -0,0 +1,57 @@
+/**
+ * Decryption of an *incoming* message: the thin layer between a resolved keystore alias and
+ * Task 39's {@link decryptEnvelope}.
+ *
+ * The only behaviour it adds is the no-op: a response that carries neither an
+ * `xenc:EncryptedKey` nor an `xenc:EncryptedData` is not an error — it is simply a response
+ * that was not encrypted — so the caller gets the document back unchanged rather than a
+ * `wss-decrypt-failed` it would have to special-case.
+ */
+import { NS } from '../../xml/namespaces.js';
+import { parseXml } from '../../xml/parse.js';
+import { findElement } from '../security-header.js';
+import { decryptEnvelope } from '../outgoing/encryption.js';
+/**
+ * Whether `xml` really carries XML-Encryption: an `xenc:EncryptedKey` or `xenc:EncryptedData`
+ * *element*, found in the DOM.
+ *
+ * A substring test (the previous implementation) says yes to a response that merely mentions
+ * those words in its text — an error message quoting them, say — and that answer turns a plain
+ * response into a `wss-decrypt-failed`. The cheap substring test stays as a pre-filter so the
+ * many responses that are not XML at all are never parsed.
+ */
+function looksEncrypted(xml) {
+    if (!xml.includes(NS.XENC) || (!xml.includes('EncryptedKey') && !xml.includes('EncryptedData'))) {
+        return false;
+    }
+    try {
+        const root = parseXml(xml, { location: 'envelope' }).documentElement;
+        if (root === null) {
+            return false;
+        }
+        return (findElement(root, NS.XENC, 'EncryptedKey') !== undefined ||
+            findElement(root, NS.XENC, 'EncryptedData') !== undefined);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decrypts an incoming message with `resolved`, or returns it untouched when it carries no
+ * XML-Encryption at all.
+ *
+ * @param xml the response envelope
+ * @param resolved the keystore alias (and passphrase) to decrypt with
+ * @returns the restored envelope and the plaintext of each decrypted block
+ * @throws WssError `wss-decrypt-failed`, `wss-algorithm-unsupported`, `wss-decryption-key-missing`
+ */
+export function decryptIncoming(xml, resolved) {
+    if (!looksEncrypted(xml)) {
+        return { xml, decrypted: [] };
+    }
+    return decryptEnvelope(xml, {
+        keystore: resolved.keystore,
+        alias: resolved.alias,
+        ...(resolved.keyPassword !== undefined ? { keyPassword: resolved.keyPassword } : {}),
+    });
+}

package/dist/wss/incoming/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Incoming WS-Security processing: what a configured response goes through after it has been
+ * read off the wire (and after MTOM expansion, so the envelope is the one the user will see).
+ *
+ * The result is deliberately a *report*, not a verdict. Nothing here throws and nothing here
+ * refuses a response: a failed signature, an untrusted signer and an expired timestamp are all
+ * recorded as failed actions and shown, because a workbench's job is to tell you exactly what
+ * the server sent, not to hide it. The caller decides what to make of that.
+ */
+import type { WssContext, WssIncomingConfig } from '../model.js';
+/** Which of the three incoming steps an action reports on. */
+export type WssActionKind = 'decrypt' | 'signature' | 'timestamp';
+/** One step of incoming processing, as the response inspector lists it. */
+export interface WssAction {
+    readonly kind: WssActionKind;
+    readonly ok: boolean;
+    /** A human-readable summary. Never carries key material, a password or a secret reference. */
+    readonly detail: string;
+    /** The signer's subject DN; only on a `signature` action whose certificate resolved. */
+    readonly signerSubject?: string;
+    /** Whether the signer is in (or chains to) the truststore; only on a `signature` action. */
+    readonly trusted?: boolean;
+    /** `wsu:Created`; only on a `timestamp` action. */
+    readonly created?: string;
+    /** `wsu:Expires`; only on a `timestamp` action that had one. */
+    readonly expires?: string;
+    /** The covered parts' element names (the reference id when unresolvable); `signature` only. */
+    readonly references?: readonly string[];
+    /** Whether a valid reference covers the envelope's `Body`; `signature` only. */
+    readonly coversBody?: boolean;
+}
+/** What {@link processIncomingWss} made of a response. */
+export interface WssResult {
+    /** One entry per step actually taken, in processing order. Empty for an unsecured response. */
+    readonly actions: readonly WssAction[];
+    /** The restored envelope, present only when decryption actually changed something. */
+    readonly decryptedXml?: string;
+    /** Every failure, as a message safe to log. Empty when every action succeeded. */
+    readonly errors: readonly string[];
+}
+/** Options for {@link processIncomingWss}. */
+export interface ProcessIncomingWssOptions {
+    /** The clock timestamp freshness (and certificate validity) is judged against. */
+    readonly clock?: () => Date;
+}
+/**
+ * Runs `config` over a response envelope: decrypt, then verify every signature on the restored
+ * document, then judge the timestamp.
+ *
+ * @param xml the response envelope as it arrived
+ * @param config the incoming configuration the request selected
+ * @param ctx the injected keystore/secret capabilities
+ * @param options an injected clock, so freshness is testable
+ * @returns the actions taken, the decrypted envelope when there was one, and any failures
+ */
+export declare function processIncomingWss(xml: string, config: WssIncomingConfig, ctx: WssContext, options?: ProcessIncomingWssOptions): Promise<WssResult>;

package/dist/wss/incoming/index.js

@@ -0,0 +1,189 @@
+/**
+ * Incoming WS-Security processing: what a configured response goes through after it has been
+ * read off the wire (and after MTOM expansion, so the envelope is the one the user will see).
+ *
+ * The result is deliberately a *report*, not a verdict. Nothing here throws and nothing here
+ * refuses a response: a failed signature, an untrusted signer and an expired timestamp are all
+ * recorded as failed actions and shown, because a workbench's job is to tell you exactly what
+ * the server sent, not to hide it. The caller decides what to make of that.
+ */
+import { isWirebenchError } from '../../errors.js';
+import { selectAlias } from '../keystore/index.js';
+import { decryptIncoming } from './decrypt.js';
+import { verifyIncoming } from './verify.js';
+/** The message of a thrown value, without the stack or any `details` a secret could hide in. */
+function messageOf(error) {
+    if (isWirebenchError(error)) {
+        return error.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/** The decrypt step: the (possibly restored) XML plus the action it produced, if any. */
+async function runDecrypt(xml, config, ctx) {
+    const ref = config.decryptKeystoreRef;
+    if (ref === undefined || ref === '') {
+        return { xml };
+    }
+    let keystore;
+    try {
+        keystore = await ctx.keystores(ref);
+    }
+    catch (error) {
+        // A resolver that rejects (a locked registry, a revoked secret) must not fail the send: the
+        // response already arrived, and the user is entitled to see it plus why it was not opened.
+        return { xml, action: { kind: 'decrypt', ok: false, detail: messageOf(error) } };
+    }
+    if (keystore === undefined) {
+        return {
+            xml,
+            action: { kind: 'decrypt', ok: false, detail: 'The decryption keystore is not available.' },
+        };
+    }
+    try {
+        const alias = selectAlias(keystore, config.decryptAlias);
+        const password = config.decryptKeyPasswordRef === undefined ? undefined : await ctx.secrets(config.decryptKeyPasswordRef);
+        const result = decryptIncoming(xml, {
+            keystore,
+            alias,
+            ...(password !== undefined ? { keyPassword: password } : {}),
+        });
+        if (result.decrypted.length === 0) {
+            // Nothing was encrypted: not a step that happened, so not a step to report.
+            return { xml: result.xml };
+        }
+        return {
+            xml: result.xml,
+            decryptedXml: result.xml,
+            action: {
+                kind: 'decrypt',
+                ok: true,
+                detail: result.decrypted.length === 1 ? 'Decrypted 1 block.' : `Decrypted ${String(result.decrypted.length)} blocks.`,
+            },
+        };
+    }
+    catch (error) {
+        return { xml, action: { kind: 'decrypt', ok: false, detail: messageOf(error) } };
+    }
+}
+/**
+ * Runs `config` over a response envelope: decrypt, then verify every signature on the restored
+ * document, then judge the timestamp.
+ *
+ * @param xml the response envelope as it arrived
+ * @param config the incoming configuration the request selected
+ * @param ctx the injected keystore/secret capabilities
+ * @param options an injected clock, so freshness is testable
+ * @returns the actions taken, the decrypted envelope when there was one, and any failures
+ */
+export async function processIncomingWss(xml, config, ctx, options) {
+    const clock = options?.clock ?? ctx.clock;
+    const actions = [];
+    const errors = [];
+    const decrypt = await runDecrypt(xml, config, ctx);
+    if (decrypt.action !== undefined) {
+        actions.push(decrypt.action);
+        if (!decrypt.action.ok) {
+            errors.push(decrypt.action.detail);
+            // Whatever the signatures cover is still ciphertext, so verifying them would report a
+            // failure whose real cause is the key, not the signature. Say so instead.
+            actions.push({
+                kind: 'signature',
+                ok: false,
+                detail: 'Signatures were not verified because the message could not be decrypted.',
+            });
+            return { actions, errors };
+        }
+    }
+    const wantsTruststore = config.signatureKeystoreRef !== undefined && config.signatureKeystoreRef !== '';
+    let truststore;
+    let truststoreError;
+    if (wantsTruststore) {
+        try {
+            truststore = await ctx.keystores(config.signatureKeystoreRef ?? '');
+        }
+        catch (error) {
+            truststoreError = `The signature truststore could not be resolved: ${messageOf(error)}`;
+        }
+        if (truststore === undefined) {
+            // Fail closed: without the truststore nothing can be trusted, and the reason is reported
+            // on the signature actions below rather than left to be read as "signer unknown".
+            truststoreError ??= 'The signature truststore is not available.';
+            errors.push(truststoreError);
+        }
+    }
+    let verified;
+    try {
+        verified = verifyIncoming(decrypt.xml, {
+            ...(truststore !== undefined ? { truststore } : {}),
+            clock,
+            skewSeconds: config.timestampSkewSeconds,
+            verifyChain: config.verifyChain,
+        });
+    }
+    catch (error) {
+        // `verifyIncoming` is written not to throw; if it ever does, that is a failed verification
+        // report, never a failed send.
+        const detail = `Verification could not be completed: ${messageOf(error)}`;
+        actions.push({ kind: 'signature', ok: false, detail, trusted: false });
+        errors.push(detail);
+        return { actions, ...(decrypt.decryptedXml !== undefined ? { decryptedXml: decrypt.decryptedXml } : {}), errors };
+    }
+    for (const signature of verified.signatures) {
+        const ok = signature.ok && signature.trusted;
+        const covered = signature.referenceNames.length === 0 ? 'nothing' : signature.referenceNames.join(', ');
+        const untrusted = truststoreError !== undefined ? `${truststoreError}` : 'but the signer is not trusted.';
+        const detail = signature.ok
+            ? signature.trusted
+                ? `Signature valid over ${covered}; signer trusted.`
+                : `Signature valid over ${covered}, ${untrusted}`
+            : (signature.error ?? 'The signature did not verify.');
+        actions.push({
+            kind: 'signature',
+            ok,
+            detail,
+            ...(signature.signerSubject !== undefined ? { signerSubject: signature.signerSubject } : {}),
+            trusted: signature.trusted,
+            references: [...signature.referenceNames],
+            coversBody: signature.coversBody,
+        });
+        if (!ok) {
+            errors.push(detail);
+        }
+    }
+    // "A signature is required" means a *valid, trusted* signature over the **Body**: a signature
+    // covering only the Timestamp leaves the payload as unprotected as no signature at all.
+    const bodySigned = verified.signatures.some((signature) => signature.ok && signature.trusted && signature.coversBody);
+    if (config.requireSignature && !bodySigned) {
+        const detail = verified.signatures.length === 0
+            ? 'This response carries no signature, and one is required.'
+            : 'No valid, trusted signature covers the Body, and one is required.';
+        actions.push({ kind: 'signature', ok: false, detail });
+        errors.push(detail);
+    }
+    const timestamp = verified.timestamp;
+    if (timestamp !== undefined) {
+        const detail = timestamp.fresh
+            ? `Timestamp fresh (created ${timestamp.created}).`
+            : (timestamp.error ?? 'The timestamp is not fresh.');
+        actions.push({
+            kind: 'timestamp',
+            ok: timestamp.fresh,
+            detail,
+            created: timestamp.created,
+            ...(timestamp.expires !== undefined ? { expires: timestamp.expires } : {}),
+        });
+        if (!timestamp.fresh) {
+            errors.push(detail);
+        }
+    }
+    else if (config.requireTimestamp) {
+        const detail = 'This response carries no timestamp, and one is required.';
+        actions.push({ kind: 'timestamp', ok: false, detail });
+        errors.push(detail);
+    }
+    return {
+        actions,
+        ...(decrypt.decryptedXml !== undefined ? { decryptedXml: decrypt.decryptedXml } : {}),
+        errors,
+    };
+}

package/dist/wss/incoming/verify.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Verification of an *incoming* message: every `ds:Signature` in a `wsse:Security` header, and
+ * the header's `wsu:Timestamp`.
+ *
+ * Two questions are answered separately, because they fail for different reasons and a user
+ * has to be able to tell them apart:
+ *
+ * - **validity** — does the signature actually hold over the bytes that arrived? That is
+ *   Task 38's {@link verifySignature}, run against the certificate the message's own `KeyInfo`
+ *   points at.
+ * - **trust** — is that certificate one we accept? A signature verifies perfectly against the
+ *   key that made it, including a key an attacker owns, so the certificate is checked against
+ *   the configured truststore: stored verbatim, or (with `verifyChain`) chaining to one of its
+ *   certificates.
+ *
+ * `KeyInfo` is therefore a *hint* about which key to look up, never a source of trust.
+ */
+import type { Keystore } from '../keystore/model.js';
+/** One `ds:Signature` as {@link verifyIncoming} judged it. */
+export interface IncomingSignatureResult {
+    /** The signature held over the bytes that arrived. */
+    readonly ok: boolean;
+    /** The `URI`s the signature's references covered, without their leading `#`. */
+    readonly references: readonly string[];
+    /** The local names of the covered elements, in reference order; the id when one is unresolvable. */
+    readonly referenceNames: readonly string[];
+    /** A valid reference covers the envelope's `Body`. `false` whenever that cannot be shown. */
+    readonly coversBody: boolean;
+    /** The signer's subject DN, when the certificate could be resolved at all. */
+    readonly signerSubject?: string;
+    /** The signer's certificate is in (or chains to) the truststore. */
+    readonly trusted: boolean;
+    /** Why the signature did not verify, or why its certificate could not be resolved. */
+    readonly error?: string;
+}
+/** The `wsu:Timestamp` as {@link verifyIncoming} read it. */
+export interface IncomingTimestampResult {
+    /** `wsu:Created`, verbatim. */
+    readonly created: string;
+    /** `wsu:Expires`, verbatim; absent when the timestamp carries none. */
+    readonly expires?: string;
+    /** `Created - skew <= now <= Expires + skew` (or, with no `Expires`, `Created` within skew). */
+    readonly fresh: boolean;
+    /** Why the timestamp was rejected; absent when fresh. */
+    readonly error?: string;
+}
+/** The outcome of {@link verifyIncoming}. */
+export interface VerifyIncomingResult {
+    readonly signatures: readonly IncomingSignatureResult[];
+    /** Absent when the message carries no `wsu:Timestamp`. */
+    readonly timestamp?: IncomingTimestampResult;
+}
+/** What {@link verifyIncoming} needs to judge a message. */
+export interface VerifyIncomingOptions {
+    /** Keystore whose aliases are the trusted certificates/CAs; without one nothing is trusted. */
+    readonly truststore?: Keystore;
+    readonly clock: () => Date;
+    /** Clock skew tolerated on the timestamp, in seconds. */
+    readonly skewSeconds: number;
+    /** Accept a signer that chains to a truststore certificate, not only one stored verbatim. */
+    readonly verifyChain: boolean;
+}
+/**
+ * Verifies every `ds:Signature` in `xml`'s `wsse:Security` headers and reads its
+ * `wsu:Timestamp`.
+ *
+ * Never throws: an unparsable, unsigned or non-SOAP message simply produces no signatures and
+ * no timestamp, which is what "this response had no WS-Security" has to look like.
+ *
+ * @param xml the (already decrypted) response envelope
+ * @param options the truststore, the clock, the tolerated skew and whether to follow chains
+ * @returns one result per signature, plus the timestamp when the message carries one
+ */
+export declare function verifyIncoming(xml: string, options: VerifyIncomingOptions): VerifyIncomingResult;