@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/crypto/smime.js

@@ -0,0 +1,402 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The CMS (S/MIME) engine behind `specs/end-to-end_encryption.md`'s "Message Format" requirement
+ * ("RapidMX MUST use S/MIME (CMS) as the on-the-wire message format for both signatures and
+ * encryption"). This module operates on raw CMS structures (`SignedData`/`EnvelopedData`) via
+ * `pkijs` — the actual MIME assembly (`multipart/signed`, RFC 9788 header protection, the
+ * `application/pkcs7-mime` wrapping) is a distinct, mechanical layer built on top of these
+ * primitives, not implemented here.
+ *
+ * Certificates are always the base64-decoded DER bytes — the same wire format
+ * `keyvaultApi.ts`'s `PublicKey.publicKey` already uses — never PEM, so this module composes
+ * directly with values read from a `Mailbox`/`Contact`'s `keys` array with no reformatting.
+ */
+import "reflect-metadata";
+import * as asn1js from "asn1js";
+import * as pkijs from "pkijs";
+// Mirrors keys.ts's own WebCrypto engine setup - both @peculiar/x509 and pkijs need to be told which
+// Crypto implementation to use; the browser/Electron renderer's own global `crypto` is exactly what
+// both expect (unlike Node's global `crypto`, which @rapidmx/restapi's server-side code has to set up
+// differently - see that repo's LocalX509CertificateAuthority.ts). The raw (`crypto`, `crypto.subtle`)
+// three-argument form, not `new pkijs.CryptoEngine({...})` - pkijs's own `CryptoEngine` class doesn't
+// actually satisfy its own `ICryptoEngine` interface (a real type-definition inconsistency in pkijs
+// itself, confirmed via `tsc --noEmit`: `generateKey`'s Ed25519/X25519 overloads don't line up between
+// the two), so passing an instance of it here fails to compile even though it works at runtime.
+pkijs.setEngine("rapidmx", crypto, crypto.subtle);
+/** SHA-256 detached signatures throughout, matching this system's hash-algorithm default everywhere
+ * else (fingerprints, HKDF). */
+const DIGEST_ALGORITHM = "SHA-256";
+/** AES-256-GCM for CMS content encryption, matching `masterKey.ts`'s own AEAD choice - one AEAD
+ * construction used consistently across this entire E2E scheme. */
+const CONTENT_ENCRYPTION_ALGORITHM = { name: "AES-GCM", length: 256 };
+/** `id-data` (RFC 5652 §4) - the only encapsulated content type S/MIME message signatures use. */
+const ID_DATA = pkijs.ContentInfo.DATA;
+/** AES-GCM content-encryption OIDs (id-aes128-GCM, id-aes192-GCM, id-aes256-GCM - RFC 5084). The only
+ * content encryption `decryptEnvelopedData()` accepts: see `UnsupportedContentEncryptionError`. */
+const AEAD_CONTENT_ENCRYPTION_OIDS = new Set(["2.16.840.1.101.3.4.1.6", "2.16.840.1.101.3.4.1.26", "2.16.840.1.101.3.4.1.46"]);
+/**
+ * Thrown by `decryptEnvelopedData()` for content encrypted with a non-AEAD algorithm (e.g. AES-CBC, 3DES).
+ * Unauthenticated CBC content is malleable - an attacker who can't read the message can still flip
+ * plaintext bits or mount EFAIL-style exfiltration gadgets against the decrypted HTML - so it is rejected
+ * outright rather than rendered with a weaker indicator.
+ *
+ * Interop note: many legacy S/MIME clients still send AES-CBC `EnvelopedData`; those messages are
+ * undecryptable in RapidMX clients by design. Everything RapidMX itself sends uses AES-256-GCM.
+ */
+export class UnsupportedContentEncryptionError extends Error {
+    constructor(algorithmOid) {
+        super(`This message uses unauthenticated content encryption (${algorithmOid}), which is not accepted.`);
+        this.name = "UnsupportedContentEncryptionError";
+        this.algorithmOid = algorithmOid;
+    }
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function parseCertificate(certDer) {
+    const asn1 = asn1js.fromBER(toArrayBuffer(certDer));
+    if (asn1.offset === -1) {
+        throw new Error("Could not parse the certificate as valid DER/BER.");
+    }
+    return new pkijs.Certificate({ schema: asn1.result });
+}
+/**
+ * Builds a detached CMS `SignedData` structure over `content`, per the spec's "Digital Signatures"
+ * section — detached, never opaque, so clients that don't understand S/MIME still render the
+ * message body. The signer's own certificate is embedded in the `certificates` field (never sent
+ * separately — unlike the encryption key, which travels in the `RapidMX-Key` header).
+ */
+export async function signDetached(content, signingCertDer, signingPrivateKey) {
+    const cert = parseCertificate(signingCertDer);
+    const signedData = new pkijs.SignedData({
+        // No `eContent` - an omitted eContent is exactly what makes this a *detached* signature per
+        // RFC 5652; the actual content is passed to sign()/verify() separately, never embedded here.
+        encapContentInfo: new pkijs.EncapsulatedContentInfo({ eContentType: pkijs.ContentInfo.DATA }),
+        signerInfos: [
+            new pkijs.SignerInfo({
+                sid: new pkijs.IssuerAndSerialNumber({ issuer: cert.issuer, serialNumber: cert.serialNumber }),
+            }),
+        ],
+        certificates: [cert],
+    });
+    await signedData.sign(signingPrivateKey, 0, DIGEST_ALGORITHM, toArrayBuffer(content));
+    const contentInfo = new pkijs.ContentInfo({ contentType: pkijs.ContentInfo.SIGNED_DATA, content: signedData.toSchema(true) });
+    return new Uint8Array(contentInfo.toSchema().toBER());
+}
+/** Verifies a detached CMS signature (as produced by `signDetached()`) against `content`. A parse
+ * failure or content-type mismatch is treated as an invalid signature (`valid: false`), not a thrown
+ * error - a malformed/foreign CMS blob is exactly the "signature failed" case the spec's Message
+ * Security Indicators table requires being able to render. */
+export async function verifyDetached(content, signatureDer) {
+    const signedData = parseSignedData(signatureDer);
+    // A detached signature MUST NOT carry encapsulated content: pkijs's verify() silently prefers an
+    // embedded eContent over the caller-supplied `data`, so accepting one here would let an attacker take
+    // ANY opaque signature the victim ever produced and staple it onto arbitrary content, which would
+    // then verify as "signed" (the round-3 review's PoC 1 - see smimeRegressions.test.ts).
+    if (!signedData || signedData.encapContentInfo.eContent) {
+        return { valid: false };
+    }
+    return verifySignerZero(signedData, toArrayBuffer(content));
+}
+/** Parses untrusted DER as a `ContentInfo` wrapping `SignedData` whose `eContentType` is `id-data`.
+ * Constructing SignedData from an untrusted schema can throw on a structurally-valid-BER-but-not-
+ * actually-SignedData blob - that degrades to `undefined` ("signature failed"), never a thrown error, per
+ * the spec's Message Security Indicators (a malformed CMS blob is exactly that state, not a crash). */
+function parseSignedData(der) {
+    try {
+        const contentInfo = pkijs.ContentInfo.fromBER(toArrayBuffer(der));
+        if (contentInfo.contentType !== pkijs.ContentInfo.SIGNED_DATA) {
+            return undefined;
+        }
+        const signedData = new pkijs.SignedData({ schema: contentInfo.content });
+        return signedData.encapContentInfo.eContentType === ID_DATA ? signedData : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Verifies `signerInfos[0]` and returns the certificate pkijs actually matched to that SignerInfo's `sid`
+ * (`extendedMode`) - never simply `certificates[0]`, which an attacker controls independently of who
+ * signed: embedding the victim's certificate first and signing with their own key (whose certificate is
+ * second) previously reported the victim's certificate as the signer (the round-3 review's PoC 2).
+ * pkijs throws a `SignedDataVerifyError` for most failures in extended mode; all degrade to invalid.
+ */
+async function verifySignerZero(signedData, data) {
+    try {
+        const result = await signedData.verify({ signer: 0, data, extendedMode: true });
+        if (result.signatureVerified !== true || !result.signerCertificate) {
+            return { valid: false };
+        }
+        return { valid: true, signerCertificateDer: new Uint8Array(result.signerCertificate.toSchema().toBER()) };
+    }
+    catch {
+        return { valid: false };
+    }
+}
+/**
+ * Extracts every email address a certificate asserts, lowercased: SAN `rfc822Name` entries when the
+ * certificate has any (RFC 5280 §4.2.1.6 - SAN is authoritative when present), otherwise the subject's
+ * legacy `emailAddress` attributes plus a `CN` that is itself an email address (how this deployment's
+ * own self-signed/test certificates and many older CAs name a mailbox). Used by `messageSecurity.ts` to
+ * bind a signer certificate to the message's claimed sender. Returns `[]` for unparseable input -
+ * including a certificate whose SubjectAlternativeName extension pkijs couldn't parse (no `parsedValue`),
+ * which then fails the identity check (`signature_failed`) rather than throwing out of message evaluation.
+ */
+export function extractCertificateEmails(certDer) {
+    let cert;
+    try {
+        cert = parseCertificate(certDer);
+    }
+    catch {
+        return [];
+    }
+    const sanEmails = [];
+    for (const extension of cert.extensions ?? []) {
+        if (extension.extnID !== "2.5.29.17") {
+            continue;
+        }
+        // pkijs parses a well-formed SubjectAlternativeName into an AltName automatically, and leaves
+        // `parsedValue` unset for a malformed one - a certificate asserting an unreadable SAN names nobody.
+        const altNames = extension.parsedValue?.altNames;
+        if (!Array.isArray(altNames)) {
+            return [];
+        }
+        for (const name of altNames) {
+            // GeneralName type 1 = rfc822Name (an IA5String value).
+            if (name.type === 1) {
+                sanEmails.push(String(name.value).toLowerCase());
+            }
+        }
+    }
+    if (sanEmails.length > 0) {
+        return sanEmails;
+    }
+    const subjectEmails = [];
+    for (const attribute of cert.subject.typesAndValues) {
+        const isEmailAttribute = attribute.type === "1.2.840.113549.1.9.1";
+        const isCommonName = attribute.type === "2.5.4.3";
+        const value = String(attribute.value.valueBlock.value).trim().toLowerCase();
+        if (isEmailAttribute || (isCommonName && /^[^\s@]+@[^\s@]+$/.test(value))) {
+            subjectEmails.push(value);
+        }
+    }
+    return subjectEmails;
+}
+/**
+ * Builds an *opaque* (content embedded, not detached) CMS `SignedData` structure over `content`.
+ * Used only when the signed message is going to be encrypted immediately afterward (`buildMessage()`
+ * in `smimeMessage.ts` composes this with `encryptForRecipients()` for the combined sign-then-encrypt
+ * case) — the spec's "Digital Signatures" section requires *detached* signing only "for
+ * signature-only messages"; once the whole thing is being encrypted regardless, there is no legacy
+ * client ever exposed to this intermediate opaque layer, so embedding the content here (simpler than
+ * building a second detached `multipart/signed` entity solely to immediately encrypt it) is
+ * conformant, not a shortcut around that requirement.
+ */
+export async function signOpaque(content, signingCertDer, signingPrivateKey) {
+    const cert = parseCertificate(signingCertDer);
+    const signedData = new pkijs.SignedData({
+        encapContentInfo: new pkijs.EncapsulatedContentInfo({
+            eContentType: pkijs.ContentInfo.DATA,
+            eContent: new asn1js.OctetString({ valueHex: toArrayBuffer(content) }),
+        }),
+        signerInfos: [
+            new pkijs.SignerInfo({
+                sid: new pkijs.IssuerAndSerialNumber({ issuer: cert.issuer, serialNumber: cert.serialNumber }),
+            }),
+        ],
+        certificates: [cert],
+    });
+    await signedData.sign(signingPrivateKey, 0, DIGEST_ALGORITHM);
+    const contentInfo = new pkijs.ContentInfo({ contentType: pkijs.ContentInfo.SIGNED_DATA, content: signedData.toSchema(true) });
+    return new Uint8Array(contentInfo.toSchema().toBER());
+}
+/** Verifies an opaque CMS signature (as produced by `signOpaque()`) and recovers its embedded
+ * content — unlike `verifyDetached()`, the content isn't supplied separately by the caller, since the
+ * whole point of an opaque signature is that it carries its own content. */
+export async function verifyOpaque(signedDer) {
+    const signedData = parseSignedData(signedDer);
+    const eContent = signedData?.encapContentInfo.eContent;
+    if (!signedData || !eContent) {
+        return { valid: false };
+    }
+    const result = await verifySignerZero(signedData);
+    if (!result.valid) {
+        return { valid: false };
+    }
+    // `.getValue()`, not `.valueBlock.valueHexView` directly - eContent commonly round-trips as a
+    // *constructed* OctetString (an outer OctetString wrapping one or more inner primitive OctetString
+    // chunks, standard per RFC 5652), and only `.getValue()` transparently concatenates those chunks;
+    // reading `.valueBlock.valueHexView` directly is only correct for a primitive OctetString and
+    // silently returns empty bytes otherwise (confirmed by direct reproduction).
+    return { ...result, content: new Uint8Array(eContent.getValue()) };
+}
+/**
+ * Builds a CMS `EnvelopedData` structure encrypting `content` to every certificate in
+ * `recipientCertDers` — per the spec's "Encrypt to Self" requirement, callers MUST include the
+ * sender's own encryption certificate in this list alongside the actual recipients' certificates, or
+ * the sender's own Sent-folder copy becomes unreadable to them.
+ */
+export async function encryptForRecipients(content, recipientCertDers) {
+    const envelopedData = new pkijs.EnvelopedData();
+    for (const certDer of recipientCertDers) {
+        envelopedData.addRecipientByCertificate(parseCertificate(certDer));
+    }
+    await envelopedData.encrypt(CONTENT_ENCRYPTION_ALGORITHM, toArrayBuffer(content));
+    const contentInfo = new pkijs.ContentInfo({ contentType: pkijs.ContentInfo.ENVELOPED_DATA, content: envelopedData.toSchema() });
+    return new Uint8Array(contentInfo.toSchema().toBER());
+}
+/**
+ * Decrypts a CMS `EnvelopedData` structure using one recipient's own certificate/private key.
+ * `EnvelopedData` doesn't label which `RecipientInfo` belongs to which recipient in a way this
+ * function's own caller already knows in advance, so it tries every recipient slot in turn with the
+ * one keypair it has, succeeding on whichever slot was actually built for it and discarding the rest
+ * — the same shape as trying every wrapped-key entry in `KeyVault.masterKeyWraps` until one unwraps.
+ * A slot whose recipient identifier names this certificate is tried first. See
+ * `decryptEnvelopedDataWithKeys()` for several candidate keys.
+ */
+export async function decryptEnvelopedData(envelopedDer, recipientCertDer, recipientPrivateKey) {
+    return decryptEnvelopedDataWithKeys(envelopedDer, [{ certDer: recipientCertDer, privateKey: recipientPrivateKey }]);
+}
+/** At most this many candidate keys are considered by `decryptEnvelopedDataWithKeys()` (further ones are ignored) - the
+ * active encryption key plus `keySession.ts`'s `MAX_RETAINED_ENCRYPTION_KEYS` retained ones. */
+export const MAX_DECRYPTION_KEYS = 21;
+/** Trial decryptions (a key tried against a slot whose recipient identifier doesn't name it) allowed for every key
+ * after the first, together. The first key keeps the unbounded every-slot trial `decryptEnvelopedData()` always did;
+ * this budget stops a message with many recipient slots from costing `slots x keys` ECDH operations. */
+export const MAX_TRIAL_DECRYPTIONS = 64;
+function bytesEqual(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+/** The recipient identifier of one `RecipientInfo`: an issuer and serial number, or a subject key identifier. Only
+ * key transport (`variant` 1) and key agreement (`variant` 2) recipients carry one naming a certificate; key agreement
+ * uses the first encrypted key's identifier, which is the only one pkijs's `decrypt()` reads. */
+function recipientIdentifier(recipientInfo) {
+    if (recipientInfo.variant === 1) {
+        return recipientInfo.value.rid;
+    }
+    if (recipientInfo.variant === 2) {
+        // pkijs refuses to parse a key agreement recipient without an encrypted key, so `[0]` always exists; a parsed
+        // identifier is variant 1 (issuer and serial number) or 2 (a `RecipientKeyIdentifier`).
+        const rid = recipientInfo.value.recipientEncryptedKeys.encryptedKeys[0].rid;
+        return rid.variant === 1 ? rid.value : rid.value.subjectKeyIdentifier;
+    }
+    return undefined;
+}
+/** The subject key identifier extension's value, when the certificate has a readable one. */
+function subjectKeyIdentifier(certificate) {
+    const extension = certificate.extensions?.find((candidate) => candidate.extnID === "2.5.29.14");
+    const parsed = extension?.parsedValue;
+    return parsed instanceof asn1js.OctetString ? new Uint8Array(parsed.valueBlock.valueHexView) : undefined;
+}
+/** Whether a recipient slot's identifier names `certificate` (same serial number and issuer DER, or same subject key
+ * identifier). A slot with no certificate identifier (KEK, password) names nobody. */
+function recipientMatchesCertificate(recipientInfo, certificate) {
+    const identifier = recipientIdentifier(recipientInfo);
+    if (identifier instanceof pkijs.IssuerAndSerialNumber) {
+        return (bytesEqual(new Uint8Array(identifier.serialNumber.valueBlock.valueHexView), new Uint8Array(certificate.serialNumber.valueBlock.valueHexView)) &&
+            bytesEqual(new Uint8Array(identifier.issuer.toSchema().toBER()), new Uint8Array(certificate.issuer.toSchema().toBER())));
+    }
+    if (identifier instanceof asn1js.OctetString) {
+        const ski = subjectKeyIdentifier(certificate);
+        return ski !== undefined && bytesEqual(new Uint8Array(identifier.valueBlock.valueHexView), ski);
+    }
+    return false;
+}
+/**
+ * Decrypts a CMS `EnvelopedData` structure with whichever of several candidate keys it was encrypted to - the mailbox's
+ * active encryption key followed by the retained older ones (`keySession.ts`'s `retainedEncryptionKeys`), so mail
+ * encrypted to a key since replaced stays readable.
+ *
+ * **Matching first:** every recipient slot whose identifier (issuer and serial number, or subject key identifier) names
+ * a candidate's certificate is tried with that key, in candidate order - normally one decryption, no guessing.
+ * **Trial otherwise** (e.g. the sender encrypted to a reissued certificate for the same key): the first candidate is
+ * tried against every remaining slot, then the others in order, sharing `MAX_TRIAL_DECRYPTIONS`.
+ *
+ * Only the first `MAX_DECRYPTION_KEYS` candidates are considered. A candidate whose certificate can't be parsed is
+ * skipped (the parse error is thrown only when no candidate is usable). Throws `UnsupportedContentEncryptionError` for
+ * non-AEAD content, and the last decryption error when no key opens any slot.
+ */
+export async function decryptEnvelopedDataWithKeys(envelopedDer, keys) {
+    const contentInfo = pkijs.ContentInfo.fromBER(toArrayBuffer(envelopedDer));
+    if (contentInfo.contentType !== pkijs.ContentInfo.ENVELOPED_DATA) {
+        throw new Error("This CMS content is not EnvelopedData.");
+    }
+    const envelopedData = new pkijs.EnvelopedData({ schema: contentInfo.content });
+    const contentEncryptionOid = envelopedData.encryptedContentInfo.contentEncryptionAlgorithm.algorithmId;
+    if (!AEAD_CONTENT_ENCRYPTION_OIDS.has(contentEncryptionOid)) {
+        throw new UnsupportedContentEncryptionError(contentEncryptionOid);
+    }
+    const candidates = [];
+    let parseError;
+    for (const key of keys.slice(0, MAX_DECRYPTION_KEYS)) {
+        try {
+            candidates.push({ certificate: parseCertificate(key.certDer), privateKey: key.privateKey });
+        }
+        catch (err) {
+            parseError = err;
+        }
+    }
+    if (candidates.length === 0) {
+        throw parseError instanceof Error ? parseError : new Error("No decryption key was supplied.");
+    }
+    const slotCount = envelopedData.recipientInfos.length;
+    const tried = new Set();
+    let lastError;
+    const attempt = async (index, candidate) => {
+        tried.add(`${index}:${candidate}`);
+        const { certificate, privateKey } = candidates[candidate];
+        try {
+            return new Uint8Array(await envelopedData.decrypt(index, { recipientCertificate: certificate, recipientPrivateKey: privateKey }));
+        }
+        catch (err) {
+            lastError = err;
+            return undefined;
+        }
+    };
+    for (let candidate = 0; candidate < candidates.length; candidate++) {
+        for (let index = 0; index < slotCount; index++) {
+            if (recipientMatchesCertificate(envelopedData.recipientInfos[index], candidates[candidate].certificate)) {
+                const decrypted = await attempt(index, candidate);
+                if (decrypted) {
+                    return decrypted;
+                }
+            }
+        }
+    }
+    let trialBudget = MAX_TRIAL_DECRYPTIONS;
+    for (let candidate = 0; candidate < candidates.length; candidate++) {
+        for (let index = 0; index < slotCount; index++) {
+            if (tried.has(`${index}:${candidate}`)) {
+                continue;
+            }
+            if (candidate > 0 && trialBudget-- <= 0) {
+                break;
+            }
+            const decrypted = await attempt(index, candidate);
+            if (decrypted) {
+                return decrypted;
+            }
+        }
+    }
+    // The `new Error(...)` fallback covers an EnvelopedData with zero recipientInfos (no attempt ever runs, so
+    // `lastError` stays its initial `undefined`) - not reachable through this module's own encryptForRecipients(),
+    // which always adds at least one recipient in practice, but kept as a defensive fallback since `lastError` could
+    // otherwise surface as a non-Error thrown value.
+    throw lastError instanceof Error ? lastError : new Error("No recipient slot in this EnvelopedData could be decrypted with these keys.");
+}
+/** SHA-256 fingerprint of a DER certificate, hex encoded — matches `keyvaultApi.ts`'s own `PublicKey.
+ * fingerprint` format exactly, so a value computed here is directly comparable against one already on
+ * a `Mailbox`/`Contact` record. Used by `messageSecurity.ts` to compare a received message's embedded
+ * signer certificate against a pinned `Contact` key per the spec's Trust Model (TOFU) — `verifyDetached()`/
+ * `verifyOpaque()` only prove a signature is mathematically valid, never that the certificate belongs to
+ * who the message claims (see `VerifyResult`'s own doc comment). */
+export async function computeCertFingerprint(certDer) {
+    const digest = await crypto.subtle.digest(DIGEST_ALGORITHM, toArrayBuffer(certDer));
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/lib/crypto/smimeMessage.d.ts

@@ -0,0 +1,132 @@
+import { DisplayBody, MimeAttachment, MimeHeaderField } from "./mime.js";
+import { type DecryptionKey } from "./smime.js";
+export interface ProtectedHeaders {
+    from: string;
+    to: string;
+    cc?: string;
+    /** An RFC 5322 date string (e.g. `new Date().toUTCString()`-shaped, `Date:`-header ready). */
+    date: string;
+    subject: string;
+    messageId: string;
+}
+/** RFC 9788's `hcp_baseline` Header Confidentiality Policy — the RFC's own required minimum default
+ * (Section 3.3). Applied to produce the OUTER, unprotected envelope's headers from the real
+ * (protected) ones; `From`/`To`/`Cc`/`Date` pass through unchanged, `Subject` is obscured. */
+export declare function applyBaselineOuterHeaders(headers: ProtectedHeaders): ProtectedHeaders;
+/** One MIME entity's worth of headers-beyond-Content-Type plus body, ready for a caller (the actual
+ * outbound-message compose step, built on top of this module) to combine with the outer envelope's
+ * own `From`/`To`/`Subject`/`Date`/`Message-ID`. */
+export interface MimePart {
+    /** The full `Content-Type` header value, including any parameters. */
+    contentType: string;
+    /** Any other headers this entity needs (`Content-Transfer-Encoding`, `Content-Disposition`, ...). */
+    additionalHeaders?: Record<string, string>;
+    body: string;
+}
+/**
+ * Builds a detached `multipart/signed` message with RFC 9788 header protection (`hp="clear"`) — per
+ * the spec, the only form signature-only messages may use (opaque signing is reserved for the
+ * sign-then-encrypt case in `buildEncryptedMessage()`, where no legacy client is ever exposed to it).
+ */
+export declare function buildSignedOnlyMessage(bodyContentType: string, bodyText: string, protectedHeaders: ProtectedHeaders, signingCertDer: Uint8Array, signingPrivateKey: CryptoKey): Promise<MimePart>;
+export interface ParsedSignedOnlyMessage {
+    verified: boolean;
+    /** The certificate pkijs matched to the verified SignerInfo (not merely the first embedded one). */
+    signerCertificateDer?: Uint8Array;
+    protectedHeaders?: ProtectedHeaders;
+    /** Every header field of the signed entity, in order, repeats included - lets a caller reject a
+     * message carrying more than one protected `From`/`To`/`Cc`/`Sender` (see `messageSecurity.ts`). */
+    protectedHeaderFields?: MimeHeaderField[];
+    bodyContentType?: string;
+    /** The inner entity's body with its Content-Transfer-Encoding/charset decoded (for a multipart inner
+     * entity this is the raw multipart text - use `displayBody` for what to render). */
+    bodyText?: string;
+    /** The displayable body: `html` only for a real text/html part, `text` for text/plain. */
+    displayBody?: DisplayBody;
+    /** The attachments inside the *signed* entity - the only ones the signature covers. */
+    attachments?: MimeAttachment[];
+}
+/** Parses and verifies a `multipart/signed` message (RFC 1847/8551). Returns `{ verified: false }` (never
+ * throws) for anything malformed — same "degrade to a failed-signature state, don't crash" contract as
+ * `smime.ts`'s own verify functions. Accepts foreign-MUA framing: unquoted/case-varied parameters,
+ * preamble/epilogue, transport padding, and a signed part stored with bare-LF line endings (retried in
+ * canonical CRLF form, which is what RFC 8551 §3.1.1 says was actually signed). The body must hold exactly two
+ * parts (RFC 1847 §2.1): a third part isn't covered by the signature, so a message carrying one is rejected
+ * rather than shown - partly unsigned - under a verified badge. */
+export declare function parseSignedOnlyMessage(contentType: string, body: string): Promise<ParsedSignedOnlyMessage>;
+/**
+ * Builds an `application/pkcs7-mime; smime-type="enveloped-data"` message with RFC 9788 header
+ * protection (`hp="cipher"`), optionally sign-then-encrypt when `signing` is supplied (opaque
+ * signing — see this module's own doc comment for why). Per the spec's "Encrypt to Self"
+ * requirement, `recipientCertDers` MUST include the sender's own encryption certificate.
+ */
+export declare function buildEncryptedMessage(bodyContentType: string, bodyText: string, protectedHeaders: ProtectedHeaders, outerHeaders: ProtectedHeaders, recipientCertDers: Uint8Array[], signing?: {
+    certDer: Uint8Array;
+    privateKey: CryptoKey;
+}): Promise<MimePart>;
+/**
+ * Combines a `MimePart` (from `buildSignedOnlyMessage()`/`buildEncryptedMessage()`) with the outer
+ * envelope's own headers into one complete RFC 5322 message source, ready for `mailApi.ts`'s
+ * `assembleDraftRaw()`. `outerHeaders` MUST be the already-obscured headers for an encrypted message
+ * (`applyBaselineOuterHeaders()`'s output) - this function does no obscuring itself, it only serializes
+ * whatever headers it's given. Deliberately excludes `Bcc`: that recipient list is submission-only and
+ * must never appear as a message header (see `AssembleDraftRawInput`'s own doc comment - `bcc` is passed
+ * to that call separately, never baked into `rawMime`). Header values are sanitized and RFC 2047-encoded
+ * the same way as the protected headers (see `headerLines()`).
+ */
+export declare function assembleOutboundMime(outerHeaders: ProtectedHeaders, part: MimePart): string;
+export interface ParsedEncryptedMessage {
+    decrypted: boolean;
+    /** Whether an inner (opaque) signature was present and verified - `undefined` when the message
+     * was encrypted without also being signed. */
+    signatureVerified?: boolean;
+    signerCertificateDer?: Uint8Array;
+    protectedHeaders?: ProtectedHeaders;
+    /** Every header field of the decrypted (and unwrapped) protected entity, in order, repeats included. */
+    protectedHeaderFields?: MimeHeaderField[];
+    bodyContentType?: string;
+    bodyText?: string;
+    /** `true` when `actualOuterHeaders` was supplied and disagrees with the `HP-Outer:` field copies
+     * found in the decrypted protected content - RFC 9788's own requirement to "visually distinguish a
+     * message whose outer and protected headers disagree" (a MITM or malicious intermediary rewrote the
+     * unprotected envelope after signing/encryption). `false` when both were supplied and agree.
+     * `undefined` when there's nothing to compare - no `actualOuterHeaders` given, or the message
+     * carries no `HP-Outer:` lines at all (a foreign sender's S/MIME implementation that doesn't write
+     * them, or a message from before this field existed). */
+    headerTamperDetected?: boolean;
+    /** The displayable body: `html` only for a real text/html part, `text` for text/plain. */
+    displayBody?: DisplayBody;
+    /** `true` when decryption was refused because the content encryption isn't AEAD (see `smime.ts`'s
+     * `UnsupportedContentEncryptionError`) - lets the caller explain that instead of "wrong key". */
+    unsupportedContentEncryption?: boolean;
+    /** The attachments inside the decrypted (and, when signed, verified) entity. */
+    attachments?: MimeAttachment[];
+}
+/** RFC 9788's `HP-Outer:` field-copy fields to actually compare - a subset of `ProtectedHeaders`
+ * (`messageId` has no `HP-Outer` counterpart; only the fields the outer envelope itself carries do).
+ * Exported so `messageSecurity.ts` can build one from a received message's real outer envelope. */
+export type ComparableOuterHeaders = Partial<Pick<ProtectedHeaders, "from" | "to" | "cc" | "date" | "subject">>;
+/** Decrypts (and, if present, verifies the inner signature of) a message built by
+ * `buildEncryptedMessage()`. Returns `{ decrypted: false }` (never throws) for anything malformed or
+ * undecryptable with the given key — the caller's own concern is distinguishing "wrong key" from
+ * "corrupt message," neither of which this function treats as exceptional.
+ *
+ * `actualOuterHeaders` — the received message's real, unprotected outer envelope headers (as the
+ * caller itself read them, before ever calling this function) — enables the RFC 9788 `HP-Outer`
+ * comparison (see `ParsedEncryptedMessage.headerTamperDetected`); omit it to skip that check entirely.
+ */
+export declare function parseEncryptedMessage(base64Body: string, recipientCertDer: Uint8Array, recipientPrivateKey: CryptoKey, actualOuterHeaders?: ComparableOuterHeaders): Promise<ParsedEncryptedMessage>;
+/** `parseEncryptedMessage()` with several candidate keys - the active encryption key first, then retained older ones -
+ * decrypted by `smime.ts`'s `decryptEnvelopedDataWithKeys()` (recipient-identifier matching first, then a bounded
+ * trial). Same never-throws contract. */
+export declare function parseEncryptedMessageWithKeys(base64Body: string, keys: DecryptionKey[], actualOuterHeaders?: ComparableOuterHeaders): Promise<ParsedEncryptedMessage>;
+/** Splits a MIME entity's raw text into its header lines (lowercased-key map, first occurrence of each
+ * name, unfolded) and raw body, plus the entity's own Content-Type value for convenience. Kept for
+ * backward compatibility - new code should use `mime.ts`'s `parseMimeEntity()`, which also exposes every
+ * repeated field in order. Tolerates bare-LF line endings. */
+export declare function splitHeadersAndBody(entity: string): {
+    headers: Record<string, string>;
+    contentType?: string;
+    body: string;
+    rawHeaderBlock: string;
+};