@wirebench/engine 2.1.1

package/dist/wss/keystore/certificate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The certificate metadata both keystore readers need — subject/issuer rendering, validity,
+ * serial and fingerprint — kept in one place so a PKCS#12 alias and a PEM alias describe the
+ * same certificate identically.
+ */
+import forge from 'node-forge';
+import type { KeystoreAlias } from './model.js';
+/** Renders a forge distinguished name as `CN=…, O=…`, in the certificate's own attribute order. */
+export declare function renderDn(attributes: readonly forge.pki.CertificateField[]): string;
+/**
+ * Renders a forge distinguished name in RFC 2253/4514 form: most specific attribute first (the
+ * reverse of the certificate's own, least-specific-first order), `,`-separated with no space,
+ * and every value escaped per {@link escapeRfc2253Value}.
+ *
+ * Used only where the DN feeds into a signature (`X509IssuerName` and friends) — the UI keeps
+ * using {@link renderDn}, which is easier to read and never needs to round-trip.
+ */
+export declare function renderDnRfc2253(attributes: readonly forge.pki.CertificateField[]): string;
+/** SHA-256 of the DER encoding, as upper-case hex in colon-separated pairs (OpenSSL's rendering). */
+export declare function fingerprintSha256(cert: forge.pki.Certificate): string;
+/** The common name of a certificate's subject, or `undefined` when it has none. */
+export declare function commonNameOf(cert: forge.pki.Certificate): string | undefined;
+/**
+ * Whether `key` is the private half of `cert`'s public key.
+ *
+ * Compares the RSA modulus, which is the only public-key field node-forge models for every key
+ * type it can parse. `false` whenever the comparison cannot be made at all (a non-RSA key, an
+ * unparsable PEM), so a caller pairing a key with a certificate never pairs them *by accident*:
+ * "cannot prove they match" and "they do not match" must both mean no.
+ *
+ * @param key the private key to test
+ * @param cert the certificate whose public key it should belong to
+ * @returns `true` only when both moduli are present and equal
+ */
+export declare function keyMatchesCertificate(key: forge.pki.PrivateKey, cert: forge.pki.Certificate): boolean;
+/** {@link keyMatchesCertificate} for a key that is still PEM text; `false` when it will not parse. */
+export declare function keyPemMatchesCertificate(keyPem: string, cert: forge.pki.Certificate): boolean;
+/** Everything but the alias name and the key: the certificate half of a {@link KeystoreAlias}. */
+export declare function describeCertificate(cert: forge.pki.Certificate): Omit<KeystoreAlias, 'alias' | 'keyPem' | 'chainPem' | 'hasPrivateKey'>;
+/**
+ * The issuer chain of `leaf`, nearest issuer first, walked through `pool`. Stops at a
+ * self-signed certificate and never visits the same certificate twice, so a cross-signed pair
+ * cannot loop. Certificates it consumed are added to `used`.
+ */
+export declare function buildChain(leaf: forge.pki.Certificate, pool: readonly forge.pki.Certificate[], used: Set<forge.pki.Certificate>): forge.pki.Certificate[];

package/dist/wss/keystore/certificate.js

@@ -0,0 +1,134 @@
+/**
+ * The certificate metadata both keystore readers need — subject/issuer rendering, validity,
+ * serial and fingerprint — kept in one place so a PKCS#12 alias and a PEM alias describe the
+ * same certificate identically.
+ */
+import forge from 'node-forge';
+/** Renders a forge distinguished name as `CN=…, O=…`, in the certificate's own attribute order. */
+export function renderDn(attributes) {
+    return attributes
+        .map((attribute) => `${attribute.shortName ?? attribute.name ?? attribute.type ?? '?'}=${String(attribute.value)}`)
+        .join(', ');
+}
+/** Characters RFC 2253/4514 requires escaping wherever they appear in an attribute value. */
+const RFC2253_ESCAPED_CHARS = new Set([',', '+', '"', '\\', '<', '>', ';', '=']);
+/**
+ * Escapes one RFC 2253/4514 attribute value: the always-escaped characters above, a leading
+ * `#` or space, a trailing space, and control characters as `\` followed by two hex digits.
+ */
+function escapeRfc2253Value(value) {
+    let out = '';
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value.charAt(index);
+        const code = value.charCodeAt(index);
+        if (RFC2253_ESCAPED_CHARS.has(char)) {
+            out += `\\${char}`;
+        }
+        else if (code < 0x20 || code === 0x7f) {
+            out += `\\${code.toString(16).padStart(2, '0')}`;
+        }
+        else if ((index === 0 && (char === '#' || char === ' ')) || (index === value.length - 1 && char === ' ')) {
+            out += `\\${char}`;
+        }
+        else {
+            out += char;
+        }
+    }
+    return out;
+}
+/**
+ * Renders a forge distinguished name in RFC 2253/4514 form: most specific attribute first (the
+ * reverse of the certificate's own, least-specific-first order), `,`-separated with no space,
+ * and every value escaped per {@link escapeRfc2253Value}.
+ *
+ * Used only where the DN feeds into a signature (`X509IssuerName` and friends) — the UI keeps
+ * using {@link renderDn}, which is easier to read and never needs to round-trip.
+ */
+export function renderDnRfc2253(attributes) {
+    return [...attributes]
+        .reverse()
+        .map((attribute) => {
+        const name = attribute.shortName ?? attribute.name ?? attribute.type ?? '?';
+        return `${name}=${escapeRfc2253Value(String(attribute.value))}`;
+    })
+        .join(',');
+}
+/** SHA-256 of the DER encoding, as upper-case hex in colon-separated pairs (OpenSSL's rendering). */
+export function fingerprintSha256(cert) {
+    const der = forge.asn1.toDer(forge.pki.certificateToAsn1(cert)).getBytes();
+    const hex = forge.md.sha256.create().update(der).digest().toHex().toUpperCase();
+    return (hex.match(/.{2}/g) ?? []).join(':');
+}
+/** The common name of a certificate's subject, or `undefined` when it has none. */
+export function commonNameOf(cert) {
+    const field = cert.subject.getField('CN');
+    const value = field?.value;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * Whether `key` is the private half of `cert`'s public key.
+ *
+ * Compares the RSA modulus, which is the only public-key field node-forge models for every key
+ * type it can parse. `false` whenever the comparison cannot be made at all (a non-RSA key, an
+ * unparsable PEM), so a caller pairing a key with a certificate never pairs them *by accident*:
+ * "cannot prove they match" and "they do not match" must both mean no.
+ *
+ * @param key the private key to test
+ * @param cert the certificate whose public key it should belong to
+ * @returns `true` only when both moduli are present and equal
+ */
+export function keyMatchesCertificate(key, cert) {
+    const modulus = key.n;
+    const certModulus = cert.publicKey.n;
+    if (modulus === undefined || certModulus === undefined) {
+        return false;
+    }
+    return modulus.toString(16) === certModulus.toString(16);
+}
+/** {@link keyMatchesCertificate} for a key that is still PEM text; `false` when it will not parse. */
+export function keyPemMatchesCertificate(keyPem, cert) {
+    try {
+        return keyMatchesCertificate(forge.pki.privateKeyFromPem(keyPem), cert);
+    }
+    catch {
+        return false;
+    }
+}
+/** A DER serial number as upper-case hex, with the leading unsigned-padding byte dropped. */
+function serialOf(cert) {
+    const raw = cert.serialNumber.toUpperCase();
+    return raw.length > 2 && raw.startsWith('00') ? raw.slice(2) : raw;
+}
+/** Everything but the alias name and the key: the certificate half of a {@link KeystoreAlias}. */
+export function describeCertificate(cert) {
+    return {
+        certPem: forge.pki.certificateToPem(cert),
+        subject: renderDn(cert.subject.attributes),
+        issuer: renderDn(cert.issuer.attributes),
+        notBefore: cert.validity.notBefore.toISOString(),
+        notAfter: cert.validity.notAfter.toISOString(),
+        serial: serialOf(cert),
+        fingerprintSha256: fingerprintSha256(cert),
+    };
+}
+/**
+ * The issuer chain of `leaf`, nearest issuer first, walked through `pool`. Stops at a
+ * self-signed certificate and never visits the same certificate twice, so a cross-signed pair
+ * cannot loop. Certificates it consumed are added to `used`.
+ */
+export function buildChain(leaf, pool, used) {
+    const chain = [];
+    let current = leaf;
+    for (;;) {
+        if (current.isIssuer(current)) {
+            return chain;
+        }
+        const issuer = pool.find((candidate) => candidate !== current && !chain.includes(candidate) && current.isIssuer(candidate));
+        if (issuer === undefined) {
+            return chain;
+        }
+        chain.push(issuer);
+        used.add(issuer);
+        current = issuer;
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Client keystores: the entry point every caller uses. `loadKeystore` dispatches on the
+ * container format, `selectAlias` picks the entry a send should present, and
+ * `toTlsClientIdentity` shapes it for `TlsOptions`.
+ */
+import type { Keystore, KeystoreAlias, LoadKeystoreOptions, TlsClientIdentity } from './model.js';
+export { loadPem } from './pem.js';
+export { loadPkcs12 } from './pkcs12.js';
+export { keystoreTypeForPath } from './model.js';
+export type { Keystore, KeystoreAlias, KeystoreDef, KeystoreType, LoadKeystoreOptions, TlsClientIdentity, } from './model.js';
+/**
+ * Parses a keystore out of its raw bytes. The engine never reads the file itself: the host
+ * checks the path and resolves the password, so containment and secret handling stay in one
+ * place (see the module docs on `model.ts`).
+ *
+ * @param bytes the keystore file's content
+ * @param options the container format and, when needed, the password
+ * @returns the parsed keystore
+ * @throws WssError `keystore-bad-password` or `keystore-invalid`
+ */
+export declare function loadKeystore(bytes: Uint8Array, options: LoadKeystoreOptions): Keystore;
+/**
+ * The alias a send should use: the one named, else — when nothing is named — the keystore's
+ * only usable entry.
+ *
+ * `alias` is "the explicit alias, else the registry's `defaultAlias`": the caller collapses
+ * those two before calling, because only it knows the registry entry.
+ *
+ * @param keystore the parsed keystore
+ * @param alias the requested alias, or `undefined` to fall back to the only entry
+ * @returns the selected alias
+ * @throws WssError `keystore-alias-missing` when the name is unknown, or when nothing is named
+ * and the keystore holds more (or fewer) than one usable entry
+ */
+export declare function selectAlias(keystore: Keystore, alias?: string): KeystoreAlias;
+/**
+ * The client identity for `alias`, shaped for `TlsOptions.cert`/`key`: the leaf with its chain
+ * concatenated after it, which is what OpenSSL expects a client to present.
+ *
+ * The chain is **not** returned as `ca`: `ca` replaces Node's trust store wholesale, so offering
+ * a keystore's own issuers as trust anchors would make selecting a client identity quietly stop
+ * public certificates from verifying. Whom to trust is configured separately from who to be.
+ *
+ * @param keystore the parsed keystore
+ * @param alias the alias to present, or `undefined` for the keystore's only identity
+ * @returns the PEM material for a TLS handshake
+ * @throws WssError `keystore-alias-missing` when the alias cannot be resolved, `keystore-invalid`
+ * when the resolved alias carries no private key
+ */
+export declare function toTlsClientIdentity(keystore: Keystore, alias?: string): TlsClientIdentity;

package/dist/wss/keystore/index.js

@@ -0,0 +1,80 @@
+/**
+ * Client keystores: the entry point every caller uses. `loadKeystore` dispatches on the
+ * container format, `selectAlias` picks the entry a send should present, and
+ * `toTlsClientIdentity` shapes it for `TlsOptions`.
+ */
+import { WssError } from '../../errors.js';
+import { loadPem } from './pem.js';
+import { loadPkcs12 } from './pkcs12.js';
+export { loadPem } from './pem.js';
+export { loadPkcs12 } from './pkcs12.js';
+export { keystoreTypeForPath } from './model.js';
+/**
+ * Parses a keystore out of its raw bytes. The engine never reads the file itself: the host
+ * checks the path and resolves the password, so containment and secret handling stay in one
+ * place (see the module docs on `model.ts`).
+ *
+ * @param bytes the keystore file's content
+ * @param options the container format and, when needed, the password
+ * @returns the parsed keystore
+ * @throws WssError `keystore-bad-password` or `keystore-invalid`
+ */
+export function loadKeystore(bytes, options) {
+    return options.type === 'pkcs12' ? loadPkcs12(bytes, options.password) : loadPem(bytes, options.password);
+}
+/**
+ * The alias a send should use: the one named, else — when nothing is named — the keystore's
+ * only usable entry.
+ *
+ * `alias` is "the explicit alias, else the registry's `defaultAlias`": the caller collapses
+ * those two before calling, because only it knows the registry entry.
+ *
+ * @param keystore the parsed keystore
+ * @param alias the requested alias, or `undefined` to fall back to the only entry
+ * @returns the selected alias
+ * @throws WssError `keystore-alias-missing` when the name is unknown, or when nothing is named
+ * and the keystore holds more (or fewer) than one usable entry
+ */
+export function selectAlias(keystore, alias) {
+    if (alias !== undefined && alias.length > 0) {
+        const found = keystore.aliases.find((candidate) => candidate.alias === alias);
+        if (found === undefined) {
+            throw new WssError('keystore-alias-missing', `The keystore has no alias "${alias}".`, { details: { alias } });
+        }
+        return found;
+    }
+    // "The only one" means the only one that can actually be presented: a keystore that also
+    // carries its CA has two entries but only ever one identity.
+    const withKey = keystore.aliases.filter((candidate) => candidate.hasPrivateKey);
+    const candidates = withKey.length > 0 ? withKey : keystore.aliases;
+    const only = candidates.length === 1 ? candidates[0] : undefined;
+    if (only === undefined) {
+        throw new WssError('keystore-alias-missing', candidates.length === 0
+            ? 'The keystore holds no entries.'
+            : 'The keystore holds several entries; choose a default alias.', { details: { count: candidates.length } });
+    }
+    return only;
+}
+/**
+ * The client identity for `alias`, shaped for `TlsOptions.cert`/`key`: the leaf with its chain
+ * concatenated after it, which is what OpenSSL expects a client to present.
+ *
+ * The chain is **not** returned as `ca`: `ca` replaces Node's trust store wholesale, so offering
+ * a keystore's own issuers as trust anchors would make selecting a client identity quietly stop
+ * public certificates from verifying. Whom to trust is configured separately from who to be.
+ *
+ * @param keystore the parsed keystore
+ * @param alias the alias to present, or `undefined` for the keystore's only identity
+ * @returns the PEM material for a TLS handshake
+ * @throws WssError `keystore-alias-missing` when the alias cannot be resolved, `keystore-invalid`
+ * when the resolved alias carries no private key
+ */
+export function toTlsClientIdentity(keystore, alias) {
+    const entry = selectAlias(keystore, alias);
+    if (entry.keyPem === undefined) {
+        throw new WssError('keystore-invalid', `The keystore alias "${entry.alias}" has no private key.`, {
+            details: { alias: entry.alias },
+        });
+    }
+    return { cert: [entry.certPem, ...entry.chainPem].join('\n'), key: entry.keyPem };
+}

package/dist/wss/keystore/model.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The shape a client keystore takes once it has been parsed: a flat list of aliases, each with
+ * its certificate (and, when the entry carries one, its private key) as PEM text.
+ *
+ * Deliberately free of any file-system access: the *host* (the desktop main process) reads the
+ * bytes after checking the path, and resolves the password out of the secret store. The engine
+ * only ever sees bytes plus an optional password, which keeps this module pure and testable and
+ * keeps every containment decision in one place.
+ */
+/** The container formats Wirebench can read a client identity out of. */
+export type KeystoreType = 'pkcs12' | 'pem';
+/** One entry of a keystore: a certificate, its chain, and — for a client identity — its key. */
+export interface KeystoreAlias {
+    /** The entry's name: its PKCS#12 `friendlyName`, else the certificate's CN, else `key-N`. */
+    readonly alias: string;
+    /** The leaf certificate, PEM-encoded. */
+    readonly certPem: string;
+    /** The private key as an unencrypted PKCS#8 (or PKCS#1) PEM; absent for a trust-only entry. */
+    readonly keyPem?: string;
+    /** Issuers above the leaf, nearest first. Empty when the keystore carries none. */
+    readonly chainPem: readonly string[];
+    /** Distinguished name, rendered `CN=…, O=…` in the certificate's own attribute order. */
+    readonly subject: string;
+    readonly issuer: string;
+    /** ISO 8601. */
+    readonly notBefore: string;
+    readonly notAfter: string;
+    /** Serial number as upper-case hex, without a leading sign byte. */
+    readonly serial: string;
+    /** SHA-256 of the DER certificate, upper-case hex in colon-separated pairs. */
+    readonly fingerprintSha256: string;
+    readonly hasPrivateKey: boolean;
+}
+/** A parsed keystore. */
+export interface Keystore {
+    readonly type: KeystoreType;
+    readonly aliases: readonly KeystoreAlias[];
+}
+/**
+ * One `wss/keystores.yaml` entry: where the keystore lives and how to open it. The password
+ * itself is never stored here — only a `secretRef` the host resolves through `safeStorage`.
+ */
+export interface KeystoreDef {
+    readonly id: string;
+    readonly name: string;
+    /** Absolute, or relative to the project root. */
+    readonly path: string;
+    readonly type: KeystoreType;
+    readonly passwordSecretRef?: string;
+    /** The name CI supplies this secret under: `WIREBENCH_SECRET_<name>`. Not a secret; committed. */
+    readonly passwordEnv?: string;
+    /** The alias a send uses when the request does not name one. */
+    readonly defaultAlias?: string;
+}
+/**
+ * The client identity a TLS handshake needs, shaped for `TlsOptions`.
+ *
+ * Deliberately *only* `cert` and `key`. A keystore says who the client is; it says nothing about
+ * whom the client should trust, and Node treats `ca` as a **replacement** trust store — so
+ * handing the keystore's own chain over as `ca` would silently drop every public root and break
+ * ordinary HTTPS endpoints the moment a client identity was selected. Server trust is configured
+ * separately.
+ */
+export interface TlsClientIdentity {
+    /** The leaf certificate with its chain concatenated after it. */
+    readonly cert: string;
+    readonly key: string;
+}
+/** Options for `loadKeystore`. */
+export interface LoadKeystoreOptions {
+    readonly type: KeystoreType;
+    /** The PKCS#12 password, or the passphrase of an encrypted PEM key. */
+    readonly password?: string;
+}
+/**
+ * The keystore type implied by a file's extension, or `undefined` for anything unrecognised.
+ * Used at "Add keystore" time so the registry records a concrete type rather than sniffing on
+ * every load.
+ *
+ * @param path the file name or path to classify
+ * @returns `'pkcs12'` for `.p12`/`.pfx`, `'pem'` for `.pem`/`.crt`/`.cer`/`.key`, else `undefined`
+ */
+export declare function keystoreTypeForPath(path: string): KeystoreType | undefined;

package/dist/wss/keystore/model.js

@@ -0,0 +1,27 @@
+/**
+ * The shape a client keystore takes once it has been parsed: a flat list of aliases, each with
+ * its certificate (and, when the entry carries one, its private key) as PEM text.
+ *
+ * Deliberately free of any file-system access: the *host* (the desktop main process) reads the
+ * bytes after checking the path, and resolves the password out of the secret store. The engine
+ * only ever sees bytes plus an optional password, which keeps this module pure and testable and
+ * keeps every containment decision in one place.
+ */
+/**
+ * The keystore type implied by a file's extension, or `undefined` for anything unrecognised.
+ * Used at "Add keystore" time so the registry records a concrete type rather than sniffing on
+ * every load.
+ *
+ * @param path the file name or path to classify
+ * @returns `'pkcs12'` for `.p12`/`.pfx`, `'pem'` for `.pem`/`.crt`/`.cer`/`.key`, else `undefined`
+ */
+export function keystoreTypeForPath(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith('.p12') || lower.endsWith('.pfx')) {
+        return 'pkcs12';
+    }
+    if (lower.endsWith('.pem') || lower.endsWith('.crt') || lower.endsWith('.key') || lower.endsWith('.cer')) {
+        return 'pem';
+    }
+    return undefined;
+}

package/dist/wss/keystore/pem.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PEM bundle reading: one or more `CERTIFICATE` blocks plus at most one private-key block, in
+ * any order — the shape `cat client.crt client.key ca.crt > client.pem` produces.
+ *
+ * Unencrypted key blocks are passed through **verbatim** rather than re-encoded: Node's `tls`
+ * accepts PKCS#1, PKCS#8 and SEC1 (EC) keys as they stand, and re-encoding them through forge
+ * would silently drop the key types forge cannot model. Only an encrypted block is decrypted,
+ * because a passphrase-protected key is exactly what the keystore password is for.
+ */
+import type { Keystore } from './model.js';
+/**
+ * Reads a PEM bundle.
+ *
+ * @param bytes the raw bundle content (UTF-8 text)
+ * @param password the passphrase of an encrypted key block, if there is one
+ * @returns a keystore with exactly one alias: the leaf, with every other certificate as chain
+ * @throws WssError `keystore-invalid` when the bytes hold no certificate or the key block is
+ * encrypted with an unsupported (non-RSA) algorithm, `keystore-bad-password` when an encrypted
+ * key block cannot be decrypted with `password`
+ */
+export declare function loadPem(bytes: Uint8Array, password?: string): Keystore;

package/dist/wss/keystore/pem.js

@@ -0,0 +1,140 @@
+/**
+ * PEM bundle reading: one or more `CERTIFICATE` blocks plus at most one private-key block, in
+ * any order — the shape `cat client.crt client.key ca.crt > client.pem` produces.
+ *
+ * Unencrypted key blocks are passed through **verbatim** rather than re-encoded: Node's `tls`
+ * accepts PKCS#1, PKCS#8 and SEC1 (EC) keys as they stand, and re-encoding them through forge
+ * would silently drop the key types forge cannot model. Only an encrypted block is decrypted,
+ * because a passphrase-protected key is exactly what the keystore password is for.
+ */
+import forge from 'node-forge';
+import { WssError } from '../../errors.js';
+import { buildChain, commonNameOf, describeCertificate, keyPemMatchesCertificate } from './certificate.js';
+/** The block types this reader treats as a private key. */
+const KEY_TYPES = new Set(['PRIVATE KEY', 'RSA PRIVATE KEY', 'EC PRIVATE KEY', 'ENCRYPTED PRIVATE KEY']);
+function invalid(message, cause) {
+    return new WssError('keystore-invalid', message, cause === undefined ? undefined : { cause });
+}
+function badPassword(cause) {
+    return new WssError('keystore-bad-password', 'The keystore password is incorrect or missing.', {
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+/** Re-renders one decoded message back to PEM text, so each block can be handled on its own. */
+function toPem(message) {
+    return forge.pem.encode(message);
+}
+/** True when the block cannot be used without a passphrase. */
+function isEncrypted(message) {
+    return message.type === 'ENCRYPTED PRIVATE KEY' || (message.procType?.type ?? '') === 'ENCRYPTED';
+}
+/**
+ * An encrypted key block whose algorithm this reader cannot open. Reported as `keystore-invalid`
+ * rather than `keystore-bad-password` so the user is not sent round the "retype the password"
+ * loop for a key that no password will ever unlock here.
+ */
+function unsupportedEncryptedKey(type, cause) {
+    return new WssError('keystore-invalid', `Encrypted "${type}" blocks are not supported: only encrypted RSA keys can be opened. ` +
+        'Convert the key to an unencrypted PEM, or use a PKCS#12 keystore.', { details: { blockType: type }, ...(cause === undefined ? {} : { cause }) });
+}
+/**
+ * A decrypted PKCS#8 `ENCRYPTED PRIVATE KEY` block, as unencrypted PKCS#8 PEM.
+ *
+ * The two failure modes are told apart deliberately: the decryption itself failing is a wrong
+ * password, while decrypting cleanly and then not parsing as RSA is an unsupported key type.
+ */
+function decryptPkcs8(pem, password) {
+    let info;
+    try {
+        info = forge.pki.decryptPrivateKeyInfo(forge.pki.encryptedPrivateKeyFromPem(pem), password);
+    }
+    catch (error) {
+        throw badPassword(error);
+    }
+    if (info === null) {
+        throw badPassword();
+    }
+    try {
+        forge.pki.privateKeyFromAsn1(info);
+    }
+    catch (error) {
+        throw unsupportedEncryptedKey('ENCRYPTED PRIVATE KEY', error);
+    }
+    return forge.pki.privateKeyInfoToPem(info);
+}
+/**
+ * The usable key PEM for `message`: the block verbatim when it is not encrypted, the decrypted
+ * PKCS#8 rendering when it is.
+ */
+function keyPemOf(message, password) {
+    const pem = toPem(message);
+    if (!isEncrypted(message)) {
+        return pem;
+    }
+    if (password === undefined || password.length === 0) {
+        throw badPassword();
+    }
+    if (message.type === 'ENCRYPTED PRIVATE KEY') {
+        return decryptPkcs8(pem, password);
+    }
+    // A legacy `Proc-Type: 4,ENCRYPTED` block names its key type in the header, so an EC or DSA
+    // one can be refused before a passphrase is even tried.
+    if (message.type !== 'RSA PRIVATE KEY') {
+        throw unsupportedEncryptedKey(message.type);
+    }
+    let key;
+    try {
+        key = forge.pki.decryptRsaPrivateKey(pem, password);
+    }
+    catch (error) {
+        throw badPassword(error);
+    }
+    if (key === null) {
+        throw badPassword();
+    }
+    return forge.pki.privateKeyInfoToPem(forge.pki.wrapRsaPrivateKey(forge.pki.privateKeyToAsn1(key)));
+}
+/**
+ * Reads a PEM bundle.
+ *
+ * @param bytes the raw bundle content (UTF-8 text)
+ * @param password the passphrase of an encrypted key block, if there is one
+ * @returns a keystore with exactly one alias: the leaf, with every other certificate as chain
+ * @throws WssError `keystore-invalid` when the bytes hold no certificate or the key block is
+ * encrypted with an unsupported (non-RSA) algorithm, `keystore-bad-password` when an encrypted
+ * key block cannot be decrypted with `password`
+ */
+export function loadPem(bytes, password) {
+    const text = Buffer.from(bytes).toString('utf8');
+    let messages;
+    try {
+        messages = forge.pem.decode(text);
+    }
+    catch (error) {
+        throw invalid('The file is not a readable PEM bundle.', error);
+    }
+    const certificates = messages
+        .filter((message) => message.type === 'CERTIFICATE')
+        .map((message) => forge.pki.certificateFromPem(toPem(message)));
+    if (certificates.length === 0) {
+        throw invalid('The PEM bundle holds no certificate.');
+    }
+    const keyMessage = messages.find((message) => KEY_TYPES.has(message.type));
+    const keyPem = keyMessage === undefined ? undefined : keyPemOf(keyMessage, password);
+    const leaf = (keyPem === undefined ? undefined : certificates.find((cert) => keyPemMatchesCertificate(keyPem, cert))) ??
+        certificates[0];
+    /* c8 ignore next 3 -- `certificates` is non-empty above, so `leaf` is always defined. */
+    if (leaf === undefined) {
+        throw invalid('The PEM bundle holds no certificate.');
+    }
+    const used = new Set([leaf]);
+    const chain = buildChain(leaf, certificates, used);
+    const alias = {
+        alias: commonNameOf(leaf) ?? 'key-0',
+        ...describeCertificate(leaf),
+        ...(keyPem === undefined ? {} : { keyPem }),
+        chainPem: chain.map((cert) => forge.pki.certificateToPem(cert)),
+        hasPrivateKey: keyPem !== undefined,
+    };
+    return { type: 'pem', aliases: [alias] };
+}

package/dist/wss/keystore/pkcs12.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { Keystore } from './model.js';
+/**
+ * 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 declare function loadPkcs12(bytes: Uint8Array, password?: string): Keystore;