@wirebench/engine 2.1.1

package/dist/wss/keystore/pkcs12.js

@@ -0,0 +1,125 @@
+/**
+ * PKCS#12 (`.p12`/`.pfx`) reading, via node-forge.
+ *
+ * A PKCS#12 file is a bag of bags: shrouded key bags, certificate bags, and attributes
+ * (`friendlyName`, `localKeyId`) that tie a key to its certificate. This module flattens that
+ * into the alias list the rest of Wirebench works with, re-exporting every private key as an
+ * unencrypted PKCS#8 PEM **in memory only** — nothing here writes to disk, and the caller is
+ * expected to keep the result out of the renderer.
+ */
+import forge from 'node-forge';
+import { WssError } from '../../errors.js';
+import { buildChain, commonNameOf, describeCertificate, keyMatchesCertificate } from './certificate.js';
+function invalid(cause) {
+    return new WssError('keystore-invalid', 'The file is not a readable PKCS#12 keystore.', { cause });
+}
+/**
+ * Wrong-password failures are the common case and must be distinguishable from a corrupt file.
+ *
+ * Matched narrowly, on forge's MAC/password wording only: a broader pattern (anything mentioning
+ * "decrypt", say) swallows genuinely malformed files and reports them as a bad password, which
+ * sends the user round a retype loop no password can end.
+ */
+function looksLikeBadPassword(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /mac could not be verified|invalid password|wrong password|password is (?:invalid|incorrect)/i.test(message);
+}
+/** A key as an unencrypted PKCS#8 PEM — what Node's `tls` accepts without a passphrase. */
+function toPkcs8Pem(key) {
+    return forge.pki.privateKeyInfoToPem(forge.pki.wrapRsaPrivateKey(forge.pki.privateKeyToAsn1(key)));
+}
+function attribute(bag, name) {
+    const value = bag.attributes?.[name]?.[0];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Every bag of one type, flattened out of forge's `{ [oid]: Bag[] }` result. */
+function bagsOfType(p12, bagType) {
+    const found = p12.getBags({ bagType });
+    return Object.values(found).flatMap((bags) => bags ?? []);
+}
+/**
+ * Reads a PKCS#12 keystore.
+ *
+ * @param bytes the raw `.p12`/`.pfx` content
+ * @param password the keystore password; an empty/absent password is tried as `''`
+ * @returns the parsed keystore, one alias per key entry plus one per unused certificate
+ * @throws WssError `keystore-bad-password` when the MAC does not verify, `keystore-invalid`
+ * when the bytes are not a PKCS#12 file at all, or when a key it holds matches none of its
+ * certificates
+ */
+export function loadPkcs12(bytes, password) {
+    const binary = forge.util.createBuffer(Buffer.from(bytes).toString('binary'));
+    let asn1;
+    try {
+        asn1 = forge.asn1.fromDer(binary);
+    }
+    catch (error) {
+        throw invalid(error);
+    }
+    let p12;
+    try {
+        p12 = forge.pkcs12.pkcs12FromAsn1(asn1, password ?? '');
+    }
+    catch (error) {
+        if (looksLikeBadPassword(error)) {
+            throw new WssError('keystore-bad-password', 'The keystore password is incorrect.', { cause: error });
+        }
+        throw invalid(error);
+    }
+    const certBags = bagsOfType(p12, forge.pki.oids['certBag'] ?? 'certBag');
+    const keyBags = [
+        ...bagsOfType(p12, forge.pki.oids['pkcs8ShroudedKeyBag'] ?? 'pkcs8ShroudedKeyBag'),
+        ...bagsOfType(p12, forge.pki.oids['keyBag'] ?? 'keyBag'),
+    ];
+    const certificates = certBags.map((bag) => bag.cert).filter((cert) => !!cert);
+    if (certificates.length === 0) {
+        throw invalid(new Error('the keystore holds no certificates'));
+    }
+    const used = new Set();
+    const aliases = [];
+    keyBags.forEach((keyBag, index) => {
+        const key = keyBag.key;
+        if (!key) {
+            return;
+        }
+        const localKeyId = attribute(keyBag, 'localKeyId');
+        // `localKeyId` is the file's own statement of which certificate belongs to this key, so it
+        // wins. Without one, the pairing is *proved* by the public key rather than guessed from bag
+        // order: a `.p12` written as [ca, leaf] would otherwise hand the client's key the CA's
+        // certificate and present an identity the key cannot sign for.
+        const certBag = certBags.find((bag) => !!bag.cert && localKeyId !== undefined && attribute(bag, 'localKeyId') === localKeyId) ??
+            certBags.find((bag) => !!bag.cert && !used.has(bag.cert) && keyMatchesCertificate(key, bag.cert));
+        const cert = certBag?.cert;
+        if (!cert) {
+            throw new WssError('keystore-invalid', 'The keystore holds a private key that matches none of its certificates.');
+        }
+        used.add(cert);
+        const chain = buildChain(cert, certificates, used);
+        aliases.push({
+            alias: attribute(keyBag, 'friendlyName') ??
+                (certBag === undefined ? undefined : attribute(certBag, 'friendlyName')) ??
+                commonNameOf(cert) ??
+                `key-${String(index)}`,
+            ...describeCertificate(cert),
+            keyPem: toPkcs8Pem(key),
+            chainPem: chain.map((issuer) => forge.pki.certificateToPem(issuer)),
+            hasPrivateKey: true,
+        });
+    });
+    // Whatever is left is a trust anchor the file happened to carry: still worth listing, so the
+    // UI can show what the user actually imported, but never usable as a client identity.
+    certBags.forEach((bag, index) => {
+        const cert = bag.cert;
+        if (!cert || used.has(cert)) {
+            return;
+        }
+        used.add(cert);
+        aliases.push({
+            alias: attribute(bag, 'friendlyName') ?? commonNameOf(cert) ?? `cert-${String(index)}`,
+            ...describeCertificate(cert),
+            chainPem: [],
+            hasPrivateKey: false,
+        });
+    });
+    return { type: 'pkcs12', aliases };
+}

package/dist/wss/model.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The WS-Security configuration model: what a project's `wss/outgoing/<id>.yaml` and
+ * `wss/incoming/<id>.yaml` describe, plus the {@link WssContext} of injected capabilities
+ * every builder takes (so nothing here reads a keystore, a secret, the clock or the entropy
+ * pool on its own — the host supplies all four, and tests supply deterministic ones).
+ */
+import type { Keystore } from './keystore/model.js';
+/** How a `wsse:UsernameToken` carries (or does not carry) its password. */
+export type WssPasswordType = 'text' | 'digest' | 'none';
+/** A `wsu:Timestamp` header element. */
+export interface WssTimestampEntry {
+    readonly kind: 'timestamp';
+    /** Seconds between `Created` and `Expires`; `0` omits `Expires` entirely. */
+    readonly timeToLiveSeconds: number;
+    /** Emit `.SSS` fractional seconds rather than whole seconds. */
+    readonly millisecondPrecision: boolean;
+}
+/** A `wsse:UsernameToken` header element. */
+export interface WssUsernameTokenEntry {
+    readonly kind: 'username-token';
+    readonly username: string;
+    /** Secret reference; the password itself is resolved by the host, never persisted. */
+    readonly passwordRef?: string;
+    readonly passwordType: WssPasswordType;
+    readonly addNonce: boolean;
+    readonly addCreated: boolean;
+}
+/**
+ * One message part a signature covers (or, from Task 39 on, an encryption entry encrypts),
+ * named the way the "Parts" table names it: by local name and namespace.
+ */
+export interface WssPart {
+    readonly name: string;
+    readonly namespace: string;
+    /** `Content` signs/encrypts the element's children, `Element` the element itself. */
+    readonly encode: 'Content' | 'Element';
+}
+/** How a signature's `wsse:SecurityTokenReference` points at the signing certificate. */
+export type WssKeyIdentifierType = 'BinarySecurityToken' | 'IssuerSerial' | 'SubjectKeyIdentifier' | 'X509KeyIdentifier' | 'Thumbprint';
+/** The RSA signature algorithms this build offers. */
+export type WssSignatureAlgorithm = 'rsa-sha256' | 'rsa-sha1';
+/** The digest algorithms this build offers, for both `SignedInfo` references and `SignatureMethod`. */
+export type WssDigestAlgorithm = 'sha256' | 'sha1';
+/**
+ * An XML Signature entry: which key signs, how the certificate is referenced, and which parts
+ * of the message are covered.
+ */
+export interface WssSignatureEntry {
+    readonly kind: 'signature';
+    /** The `wss/keystores.yaml` registry id holding the signing key. */
+    readonly keystoreRef: string;
+    /** Alias inside that keystore; falls back to the configuration's `defaultAlias`. */
+    readonly alias?: string;
+    /** Secret reference for the private key's passphrase, when its PEM is encrypted. */
+    readonly keyPasswordRef?: string;
+    readonly keyIdentifierType: WssKeyIdentifierType;
+    readonly signatureAlgorithm: WssSignatureAlgorithm;
+    readonly digestAlgorithm: WssDigestAlgorithm;
+    /** Only exclusive canonicalization is offered; the field exists so documents stay explicit. */
+    readonly canonicalization: 'exc-c14n';
+    /** Emit only the leaf certificate (`X509v3`) rather than the whole path (`X509PKIPathv1`). */
+    readonly useSingleCertificate: boolean;
+    readonly parts: readonly WssPart[];
+}
+/** The parts a new signature entry covers: the SOAP `Body` and the WS-Security `Timestamp`. */
+export declare const DEFAULT_WSS_SIGNATURE_PARTS: readonly WssPart[];
+/** The block ciphers (and modes) this build encrypts message parts with. */
+export type WssSymmetricAlgorithm = 'aes128-cbc' | 'aes256-cbc' | 'aes128-gcm' | 'aes256-gcm';
+/** How the per-message symmetric key is wrapped for the recipient. */
+export type WssKeyTransportAlgorithm = 'rsa-oaep' | 'rsa-1_5';
+/**
+ * An XML Encryption entry: whose certificate the message is encrypted *to*, how that
+ * certificate is referenced, which algorithms are used, and which parts are encrypted.
+ *
+ * Only the recipient's **certificate** is needed — encryption uses its public key, so the
+ * keystore alias this names never has to carry a private key.
+ */
+export interface WssEncryptionEntry {
+    readonly kind: 'encryption';
+    /** The `wss/keystores.yaml` registry id holding the recipient's certificate. */
+    readonly keystoreRef: string;
+    /** Alias inside that keystore; falls back to the configuration's `defaultAlias`. */
+    readonly alias?: string;
+    readonly keyIdentifierType: WssKeyIdentifierType;
+    readonly symmetricAlgorithm: WssSymmetricAlgorithm;
+    readonly keyTransportAlgorithm: WssKeyTransportAlgorithm;
+    /** Embed the recipient certificate as a `wsse:BinarySecurityToken` rather than referencing one. */
+    readonly embedKey: boolean;
+    /** Wrap the symmetric key in an `xenc:EncryptedKey`; `false` means it is shared out of band. */
+    readonly encryptSymmetricKey: boolean;
+    readonly parts: readonly WssPart[];
+}
+/** The parts a new encryption entry covers: the SOAP `Body`'s content. */
+export declare const DEFAULT_WSS_ENCRYPTION_PARTS: readonly WssPart[];
+/** One element of an outgoing WS-Security configuration, applied in configuration order. */
+export type WssEntry = WssTimestampEntry | WssUsernameTokenEntry | WssSignatureEntry | WssEncryptionEntry;
+/** Every entry kind, in the order the editor offers them. */
+export declare const WSS_ENTRY_KINDS: readonly ["timestamp", "username-token", "signature", "encryption"];
+/** One `wss/outgoing/<id>.yaml` document. */
+export interface WssOutgoingConfig {
+    readonly id: string;
+    readonly name: string;
+    /** Keystore alias entries default to when they name none. */
+    readonly defaultAlias?: string;
+    /** Secret reference username tokens default to when they name none. */
+    readonly defaultPasswordRef?: string;
+    /** SOAP actor/role the `wsse:Security` header is addressed to. */
+    readonly actor?: string;
+    /** Set `mustUnderstand` on the `wsse:Security` header. */
+    readonly mustUnderstand: boolean;
+    readonly entries: readonly WssEntry[];
+}
+/**
+ * One `wss/incoming/<id>.yaml` document: how a *response* is decrypted and how its signatures
+ * and timestamp are judged.
+ */
+export interface WssIncomingConfig {
+    readonly id: string;
+    readonly name: string;
+    /** Keystore holding the private key incoming `xenc:EncryptedKey` blocks are opened with. */
+    readonly decryptKeystoreRef?: string;
+    /** Alias inside that keystore; the keystore's first (or default) alias when omitted. */
+    readonly decryptAlias?: string;
+    /** Secret reference for that private key's passphrase, when its PEM is encrypted. */
+    readonly decryptKeyPasswordRef?: string;
+    /** Truststore: a keystore whose aliases are the certificates (or CAs) incoming signatures are trusted from. */
+    readonly signatureKeystoreRef?: string;
+    /** Report a failed `signature` action when the response carries no `ds:Signature` at all. */
+    readonly requireSignature: boolean;
+    /** Report a failed `timestamp` action when the response carries no `wsu:Timestamp`. */
+    readonly requireTimestamp: boolean;
+    /** Clock skew tolerated on `wsu:Created`/`wsu:Expires`, in seconds. */
+    readonly timestampSkewSeconds: number;
+    /** Accept a signer that chains to a truststore certificate, not only one stored verbatim. */
+    readonly verifyChain: boolean;
+}
+/** The defaults a new incoming configuration starts from. */
+export declare const DEFAULT_WSS_TIMESTAMP_SKEW_SECONDS = 300;
+/**
+ * Everything a WS-Security operation needs from the outside world. All five members are
+ * injectable: the host wires them to the real keystore loader, the secret store and
+ * `node:crypto`; tests wire them to fixtures and a frozen clock.
+ */
+export interface WssContext {
+    /** Resolves a `wss/keystores.yaml` entry id to its parsed keystore. */
+    readonly keystores: (ref: string) => Promise<Keystore | undefined>;
+    /** Resolves a secret reference to its plaintext. Only ever called inside the host process. */
+    readonly secrets: (ref: string) => Promise<string | undefined>;
+    readonly clock: () => Date;
+    readonly nonce: (bytes: number) => Uint8Array;
+    readonly uuid: () => string;
+}
+/**
+ * A {@link WssContext} with real defaults: no keystores, no secrets, the system clock and
+ * `node:crypto` entropy. Any member given in `overrides` replaces its default.
+ *
+ * @param overrides the members the caller can actually provide
+ * @returns a complete context
+ */
+export declare function createWssContext(overrides?: Partial<WssContext>): WssContext;

package/dist/wss/model.js

@@ -0,0 +1,37 @@
+/**
+ * The WS-Security configuration model: what a project's `wss/outgoing/<id>.yaml` and
+ * `wss/incoming/<id>.yaml` describe, plus the {@link WssContext} of injected capabilities
+ * every builder takes (so nothing here reads a keystore, a secret, the clock or the entropy
+ * pool on its own — the host supplies all four, and tests supply deterministic ones).
+ */
+import { randomBytes, randomUUID } from 'node:crypto';
+import { NS } from '../xml/namespaces.js';
+/** The parts a new signature entry covers: the SOAP `Body` and the WS-Security `Timestamp`. */
+export const DEFAULT_WSS_SIGNATURE_PARTS = [
+    { name: 'Body', namespace: NS.SOAP11_ENV, encode: 'Content' },
+    { name: 'Timestamp', namespace: NS.WSU, encode: 'Content' },
+];
+/** The parts a new encryption entry covers: the SOAP `Body`'s content. */
+export const DEFAULT_WSS_ENCRYPTION_PARTS = [
+    { name: 'Body', namespace: NS.SOAP11_ENV, encode: 'Content' },
+];
+/** Every entry kind, in the order the editor offers them. */
+export const WSS_ENTRY_KINDS = ['timestamp', 'username-token', 'signature', 'encryption'];
+/** The defaults a new incoming configuration starts from. */
+export const DEFAULT_WSS_TIMESTAMP_SKEW_SECONDS = 300;
+/**
+ * A {@link WssContext} with real defaults: no keystores, no secrets, the system clock and
+ * `node:crypto` entropy. Any member given in `overrides` replaces its default.
+ *
+ * @param overrides the members the caller can actually provide
+ * @returns a complete context
+ */
+export function createWssContext(overrides) {
+    return {
+        keystores: overrides?.keystores ?? (() => Promise.resolve(undefined)),
+        secrets: overrides?.secrets ?? (() => Promise.resolve(undefined)),
+        clock: overrides?.clock ?? (() => new Date()),
+        nonce: overrides?.nonce ?? ((bytes) => new Uint8Array(randomBytes(bytes))),
+        uuid: overrides?.uuid ?? (() => randomUUID()),
+    };
+}

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

@@ -0,0 +1,76 @@
+/**
+ * XML Encryption (W3C XML-Enc 1.0/1.1) for a WS-Security header, implemented directly on
+ * `node:crypto`.
+ *
+ * The spec-approved `xml-encryption` package was evaluated first and rejected: it does every
+ * algorithm this build needs, but it emits one fixed shape — an `xenc:EncryptedData` of
+ * `Type="…#Element"` with the `xenc:EncryptedKey` *nested inside its own `ds:KeyInfo`* — with
+ * no `Id`, no `Type="…#Content"`, no `xenc:ReferenceList`/`xenc:DataReference`, and no
+ * `wsse:SecurityTokenReference` key identifiers. WS-Security needs the opposite arrangement
+ * (one `EncryptedKey` in the `wsse:Security` header, referencing the `EncryptedData` blocks it
+ * keyed), so adopting it would mean rebuilding its output string and using only its ~40 lines
+ * of `node:crypto` calls. Those are written here instead, and no dependency was added.
+ *
+ * Ciphertext layout, per XML-Enc §5.2 and XML-Enc 1.1 §5.2.4: CBC is `IV(16) ‖ ciphertext`
+ * (PKCS#7 padded), GCM is `IV(12) ‖ ciphertext ‖ tag(16)`. Key transport is RSA-OAEP with a
+ * SHA-1 digest and MGF1-SHA1 (§5.4.2), or raw PKCS#1 v1.5.
+ *
+ * Unlike `signEnvelope`, this mutates `doc` in place and never re-serializes it, so elements
+ * the caller held stay valid — but `applyOutgoingWss` re-resolves the header anyway, because a
+ * *signature* entry earlier in the same configuration may already have swapped the document.
+ */
+import type { Document } from '@xmldom/xmldom';
+import type { Keystore, KeystoreAlias } from '../keystore/model.js';
+import type { WssContext, WssEncryptionEntry } from '../model.js';
+/** The keystore material {@link encryptEnvelope} encrypts *to*; only the certificate is used. */
+export interface ResolvedEncryptionKey {
+    readonly keystore: Keystore;
+    readonly alias: KeystoreAlias;
+    /** The actor/role of the `wsse:Security` block the `xenc:EncryptedKey` belongs in. */
+    readonly actor?: string;
+}
+/** What {@link decryptEnvelope} needs to open an envelope. */
+export interface DecryptEnvelopeOptions {
+    readonly keystore: Keystore;
+    /** The alias whose private key unwraps the `xenc:EncryptedKey`. */
+    readonly alias: KeystoreAlias;
+    /** Passphrase for an encrypted private key PEM. Resolved by the host; never logged. */
+    readonly keyPassword?: string;
+}
+/** The outcome of {@link decryptEnvelope}. */
+export interface DecryptEnvelopeResult {
+    /** The envelope with every `xenc:EncryptedData` replaced by its plaintext. */
+    readonly xml: string;
+    /** The plaintext of each decrypted block, in the order the `ReferenceList` named them. */
+    readonly decrypted: readonly string[];
+}
+/**
+ * Encrypts the parts `entry` names and, when `entry.encryptSymmetricKey`, appends one
+ * `<xenc:EncryptedKey>` to the `wsse:Security` block addressed to `resolved.actor`.
+ *
+ * The `EncryptedKey` is *appended*, so its position in the header matches the entry's position
+ * in the configuration: `[encryption, signature]` puts it before the `ds:Signature` (which
+ * therefore covers it), `[signature, encryption]` puts it after.
+ *
+ * @param doc the envelope, already carrying its `wsse:Security` header
+ * @param entry the encryption configuration
+ * @param resolved the keystore alias whose certificate the message is encrypted to
+ * @param ctx the injected entropy/uuid capabilities
+ * @throws WssError `wss-not-an-envelope`, `wss-part-missing`, `wss-ski-missing`
+ */
+export declare function encryptEnvelope(doc: Document, entry: WssEncryptionEntry, resolved: ResolvedEncryptionKey, ctx: WssContext): void;
+/**
+ * Decrypts every `xenc:EncryptedData` in `xml` that `alias`'s private key can open, restoring
+ * the original `Content`/`Element` in place and removing the consumed `xenc:EncryptedKey` from
+ * the `wsse:Security` header.
+ *
+ * The `EncryptedKey` whose `ds:KeyInfo` names `alias`'s certificate is preferred; when none
+ * does (a key identifier form this build cannot compute, say), every `EncryptedKey` is tried
+ * and the first one that unwraps wins. A key that does not fit fails closed.
+ *
+ * @param xml the encrypted envelope
+ * @param options the keystore alias 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 decryptEnvelope(xml: string, options: DecryptEnvelopeOptions): DecryptEnvelopeResult;