@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/crypto/messageSecurity.js

@@ -0,0 +1,367 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Evaluates a *received* message's raw MIME source into one of `specs/end-to-end_encryption.md`'s
+ * "Message Security Indicators" states, and recovers the plaintext body when applicable. Reads the
+ * outer envelope's own `Content-Type` (via `mime.ts`'s `parseMimeEntity()`) to decide whether the message
+ * is `multipart/signed`, `application/pkcs7-mime; smime-type="enveloped-data"`, or neither.
+ *
+ * **What a verified state means.** `"signed_verified"`/`"encrypted_verified"` require ALL of: (1) a
+ * cryptographically valid CMS signature (`smime.ts` - detached signatures carrying their own eContent are
+ * rejected, the signer certificate is the one matched to the SignerInfo, never simply the first embedded
+ * certificate, and a `multipart/signed` body must hold exactly the signed part and the signature); (2) the
+ * signer certificate's fingerprint is one the reader already trusts - a pinned `Contact` signing key passed
+ * as `pinnedSignerFingerprints`, or the unlocked mailbox's own `signingFingerprint`; (3) the signer
+ * certificate names the sender: one of its email addresses (SAN rfc822Name, else subject emailAddress /
+ * email-shaped CN) equals the single address in the protected `From` (or the outer `From` when the signed
+ * content carries no protected headers, as with non-RFC 9788 senders); (4) the protected `From`/`To`/`Cc`
+ * address sets (when present) equal the outer envelope's, a signed-only message's protected `Subject` equals
+ * its outer one (what the mail list shows), and neither header block carries more than one
+ * `From`/`To`/`Cc`/`Sender` field.
+ *
+ * **No trust anchor, no verified badge.** Certificates aren't chain-validated (there is no trust store), so
+ * checks 1, 3 and 4 alone prove only that *someone* holding a certificate naming the sender signed it - a
+ * self-issued certificate with SAN `ceo@victim.com` passes them. Without a matching pin the result is
+ * `"signed_unverified_signer"`/`"encrypted_unverified_signer"` instead, carrying `signerFingerprint` and
+ * `signerEmails` so a UI can show "signed by an unverified certificate" and offer to trust it. A failure of checks 1, 3
+ * or 4 is `"signature_failed"` with `signatureFailureReason` saying which check failed.
+ *
+ * **Pinned, but a different key.** When pins were supplied and checks 1, 3 and 4 pass but the signer matches no pin, the
+ * result is `"signature_failed"` with `signatureFailureReason: "signer_key_changed"`: the sender's certificate names
+ * them and the message is intact, but it isn't the key the reader pinned (a rotation the reader hasn't accepted, or an
+ * impersonation). Only this failure also carries `signerCertificate`, so a UI can compare it with the pinned keys
+ * (`contactsApi.ts`'s `fetchSignerKeyState()`) and let the user accept or reject it (`keyvaultApi.ts`'s
+ * `resolveKeyConflict()`). A pin mismatch whose certificate also fails check 3 or 4 (or couldn't be resolved) stays
+ * `untrusted_signer`. Previously pinned keys count as pins (see `signingKeyFingerprints()`), so mail signed before an
+ * accepted or automatic rotation still verifies.
+ */
+import { decodeHeaderText, extractAddresses, parseMimeEntity, parseParameterizedHeader, plainTextToHtml } from "./mime.js";
+import { toBase64 } from "./encoding.js";
+import { computeCertFingerprint, extractCertificateEmails } from "./smime.js";
+import { parseEncryptedMessageWithKeys, parseSignedOnlyMessage } from "./smimeMessage.js";
+import { isTrustedForVerification } from "./keyvaultApi.js";
+import { KeysLockedError } from "./masterKey.js";
+import { buildVerificationSeal, openVerificationSeal, rawMimeSha256 } from "./verificationSeal.js";
+export { signingKeyFingerprints } from "./keyvaultApi.js";
+function isSignedOnlyContentType(contentTypeValue) {
+    return contentTypeValue === "multipart/signed";
+}
+/** Matches `buildEncryptedMessage()`'s own output shape, and leniently accepts the equivalent legacy/
+ * AEAD `smime-type` values a foreign S/MIME sender could produce (mirrors `@rapidmx/restapi`'s own
+ * server-side `SmimeUtils.isEncryptedBody()` classification, so the two systems agree on what counts as
+ * encrypted). Parameters are matched case-insensitively, quoted or not. */
+function isEncryptedContentType(contentType) {
+    if (contentType.value === "multipart/encrypted") {
+        return true;
+    }
+    if (!contentType.value.endsWith("pkcs7-mime")) {
+        return false;
+    }
+    const smimeType = contentType.params["smime-type"]?.toLowerCase();
+    return smimeType === "enveloped-data" || smimeType === "authenveloped-data";
+}
+const NO_KEY_ERROR = "This device doesn't have the key needed to decrypt this message.";
+const UNSUPPORTED_ENCRYPTION_ERROR = "This message uses an older, unauthenticated encryption algorithm that RapidMX doesn't accept, so it can't be opened safely.";
+function renderDisplayBody(display) {
+    if (display?.html !== undefined) {
+        return { html: display.html };
+    }
+    if (display?.text !== undefined) {
+        return { html: plainTextToHtml(display.text), text: display.text };
+    }
+    return {};
+}
+function sameAddressSet(a, b) {
+    const left = new Set(a);
+    const right = new Set(b);
+    return left.size === right.size && [...left].every((address) => right.has(address));
+}
+/** Normalizes whitespace runs, so a Subject refolded in transit still compares equal. */
+function normalizeSubject(value) {
+    return decodeHeaderText(value ?? "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Address header fields a message must carry at most once (RFC 5322 §3.6 allows exactly zero or one). */
+const SINGLETON_ADDRESS_FIELDS = ["from", "to", "cc", "sender"];
+function hasRepeatedAddressField(fields) {
+    const counts = new Map();
+    for (const { name } of fields ?? []) {
+        const key = name.toLowerCase();
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return SINGLETON_ADDRESS_FIELDS.some((name) => (counts.get(name) ?? 0) > 1);
+}
+function normalizePins(pins) {
+    return (Array.isArray(pins) ? pins : pins === undefined ? [] : [pins]).map((pin) => pin.toLowerCase());
+}
+/** Checks 2-4 from this module's doc comment for an already cryptographically verified signature.
+ * Returns `undefined` when the signer is accepted, otherwise the failure reason. A pin mismatch is
+ * `"signer_key_changed"` when checks 3 and 4 pass for the certificate, and `"untrusted_signer"` when they don't (or no
+ * certificate was resolved).
+ *
+ * With no `pinnedSignerFingerprint` (or an empty array), check 2 is skipped and `undefined` means only that the
+ * certificate names the sender consistently - NOT that the signer is trusted. Use `evaluateMessageSecurity()`
+ * (which reports that case as `*_unverified_signer`) unless you enforce a pin yourself. */
+export async function checkSignerBinding(input) {
+    const pins = normalizePins(input.pinnedSignerFingerprint);
+    // Fail closed: an absent certificate hashes/extracts as empty, which can never match a pin or From.
+    const certDer = input.signerCertificateDer ?? new Uint8Array();
+    if (pins.length > 0 && !pins.includes(await computeCertFingerprint(certDer))) {
+        // A certificate that otherwise binds cleanly to the sender is a key change for the user to judge; anything else
+        // (no certificate, wrong identity, header tampering) stays a plain untrusted signer.
+        return input.signerCertificateDer && checkIdentityAndHeaders(input, certDer) === undefined ? "signer_key_changed" : "untrusted_signer";
+    }
+    return checkIdentityAndHeaders(input, certDer);
+}
+/** Checks 3-4 from this module's doc comment. */
+function checkIdentityAndHeaders(input, certDer) {
+    const { protectedHeaders, outerHeaders } = input;
+    if (hasRepeatedAddressField(input.outerFields) || hasRepeatedAddressField(input.protectedFields)) {
+        return "header_mismatch";
+    }
+    const outerFrom = extractAddresses(outerHeaders["from"]);
+    const protectedFrom = extractAddresses(protectedHeaders?.from);
+    const senderAddresses = protectedFrom.length > 0 ? protectedFrom : outerFrom;
+    if (senderAddresses.length !== 1 || !extractCertificateEmails(certDer).includes(senderAddresses[0])) {
+        return "signer_identity_mismatch";
+    }
+    const protectedTo = extractAddresses(protectedHeaders?.to);
+    if (!sameAddressSet(senderAddresses, outerFrom) || (protectedTo.length > 0 && !sameAddressSet(protectedTo, extractAddresses(outerHeaders["to"])))) {
+        return "header_mismatch";
+    }
+    if (protectedFrom.length > 0) {
+        // RFC 9788 protected headers are present, so Cc (possibly absent on both sides) and - for a signed-only
+        // message - Subject were signed: an outer copy that differs was changed (or added) after signing.
+        if (!sameAddressSet(extractAddresses(protectedHeaders?.cc), extractAddresses(outerHeaders["cc"]))) {
+            return "header_mismatch";
+        }
+        if (input.compareSubject && normalizeSubject(protectedHeaders?.subject) !== normalizeSubject(outerHeaders["subject"])) {
+            return "header_mismatch";
+        }
+    }
+    return undefined;
+}
+/**
+ * Evaluates one received message's raw MIME source (see `mailApi.ts`'s `getMessageRawContent()`) into
+ * a security state + recovered plaintext. Never throws — a parse failure, wrong key, or unrecognized
+ * content type all degrade to a result the caller can render directly.
+ *
+ * `pinnedSignerFingerprints` - the sender's trusted signing-key fingerprint(s): `signingKeyFingerprints()` of the
+ * sender's `Contact.keys` and `Contact.previousKeys` (see `contactsApi.ts`'s `fetchPinnedSigningFingerprints()`). A
+ * supplied pin that the signer doesn't match is `signer_key_changed` or `untrusted_signer`. The unlocked mailbox's own
+ * `signingFingerprint` is always trusted too (mail this mailbox signed itself). Omitted or empty, a valid signature
+ * from any other certificate is `*_unverified_signer`, never verified. `readerAddress` - the unlocked mailbox's own
+ * address - enables `notAddressedToReader`.
+ *
+ * An encrypted message is decrypted with `unlocked`'s active encryption key or any of its `retainedEncryptionKeys` (the
+ * older keys a rotation replaced - see `keySession.ts`), matched by recipient identifier first.
+ */
+export async function evaluateMessageSecurity(rawMime, unlocked, pinnedSignerFingerprints, readerAddress) {
+    return (await evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress)).result;
+}
+async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress) {
+    const { headers, body, fields } = parseMimeEntity(rawMime);
+    const rawContentType = headers["content-type"];
+    if (!rawContentType) {
+        return { result: { state: "unprotected" }, kind: "other" };
+    }
+    const contentType = parseParameterizedHeader(rawContentType);
+    const callerPins = normalizePins(pinnedSignerFingerprints);
+    // The received message's own *real* outer envelope - what `HP-Outer`'s field copies (written at
+    // send time, inside the encrypted content) are compared against to detect post-send tampering.
+    const actualOuterHeaders = {
+        from: headers["from"],
+        to: headers["to"],
+        cc: headers["cc"],
+        date: headers["date"],
+        subject: headers["subject"],
+    };
+    /** Runs checks 2-4 and resolves the trust outcome: a failure reason, or whether a pin matched. */
+    const checkSigner = async (signerCertificateDer, protectedHeaders, protectedFields, compareSubject) => {
+        const certDer = signerCertificateDer ?? new Uint8Array();
+        const fingerprint = await computeCertFingerprint(certDer);
+        const signer = signerCertificateDer ? { signerFingerprint: fingerprint, signerEmails: extractCertificateEmails(certDer) } : {};
+        // The certificate itself (for "trust this signer" or a key-changed comparison) only accompanies a signature that
+        // didn't fail or failed only as `signer_key_changed` - both always have a certificate (a missing one fails the
+        // binding check closed as another reason), so `certDer` is the real one.
+        const acceptedSigner = { ...signer, signerCertificate: toBase64(certDer) };
+        const trustedPins = unlocked?.signingFingerprint ? [...callerPins, unlocked.signingFingerprint.toLowerCase()] : callerPins;
+        const failure = await checkSignerBinding({
+            signerCertificateDer,
+            protectedHeaders,
+            outerHeaders: headers,
+            outerFields: fields,
+            protectedFields,
+            // Only pins the caller supplied make a mismatch a failure; the mailbox's own key alone never does.
+            pinnedSignerFingerprint: callerPins.length > 0 ? trustedPins : undefined,
+            compareSubject,
+        });
+        return { failure, trusted: trustedPins.includes(fingerprint), signer, acceptedSigner };
+    };
+    const addressing = (protectedHeaders) => {
+        const recipients = [...extractAddresses(protectedHeaders?.to), ...extractAddresses(protectedHeaders?.cc)];
+        if (!readerAddress || recipients.length === 0) {
+            return {};
+        }
+        return { notAddressedToReader: !recipients.includes(readerAddress.trim().toLowerCase()) };
+    };
+    const exposedHeaders = (protectedHeaders) => {
+        if (!protectedHeaders || extractAddresses(protectedHeaders.from).length === 0) {
+            return {};
+        }
+        const { from, to, cc, subject } = protectedHeaders;
+        return { protectedHeaders: { from, to, ...(cc !== undefined ? { cc } : {}), subject } };
+    };
+    if (isSignedOnlyContentType(contentType.value)) {
+        const parsed = await parseSignedOnlyMessage(rawContentType, body);
+        if (!parsed.verified) {
+            return { result: { state: "signature_failed", signatureFailureReason: "invalid_signature" }, kind: "signed" };
+        }
+        const { failure, trusted, signer, acceptedSigner } = await checkSigner(parsed.signerCertificateDer, parsed.protectedHeaders, parsed.protectedHeaderFields, true);
+        const content = {
+            ...renderDisplayBody(parsed.displayBody),
+            subject: parsed.protectedHeaders?.subject || undefined,
+            ...exposedHeaders(parsed.protectedHeaders),
+            attachments: parsed.attachments,
+        };
+        if (failure) {
+            const result = { state: "signature_failed", signatureFailureReason: failure, ...(failure === "signer_key_changed" ? acceptedSigner : signer) };
+            return { result, kind: "signed", ...(failure === "signer_key_changed" ? { signedContent: { ...content, ...addressing(parsed.protectedHeaders) } } : {}) };
+        }
+        return {
+            result: { state: trusted ? "signed_verified" : "signed_unverified_signer", ...content, ...acceptedSigner, ...addressing(parsed.protectedHeaders) },
+            kind: "signed",
+        };
+    }
+    if (isEncryptedContentType(contentType)) {
+        // The active key first, then the retained older ones (see `keySession.ts`'s `retainedEncryptionKeys`), so mail
+        // encrypted to a key since replaced still opens. Only ever used to decrypt here - never to encrypt or sign.
+        const keys = [
+            ...(unlocked?.encryptionPrivateKey && unlocked.encryptionCertDer ? [{ certDer: unlocked.encryptionCertDer, privateKey: unlocked.encryptionPrivateKey }] : []),
+            ...(unlocked?.retainedEncryptionKeys ?? []).map(({ certDer, privateKey }) => ({ certDer, privateKey })),
+        ];
+        if (keys.length === 0) {
+            return { result: { state: "encrypted", decryptError: NO_KEY_ERROR }, kind: "encrypted" };
+        }
+        const parsed = await parseEncryptedMessageWithKeys(body, keys, actualOuterHeaders);
+        if (!parsed.decrypted) {
+            return { result: { state: "encrypted", decryptError: parsed.unsupportedContentEncryption ? UNSUPPORTED_ENCRYPTION_ERROR : NO_KEY_ERROR }, kind: "encrypted" };
+        }
+        const content = {
+            ...renderDisplayBody(parsed.displayBody),
+            headerTamperDetected: parsed.headerTamperDetected,
+            subject: parsed.protectedHeaders?.subject || undefined,
+            ...exposedHeaders(parsed.protectedHeaders),
+            attachments: parsed.attachments,
+            ...addressing(parsed.protectedHeaders),
+        };
+        if (parsed.signatureVerified === undefined) {
+            return { result: { state: "encrypted", ...content }, kind: "encrypted" };
+        }
+        if (!parsed.signatureVerified) {
+            return { result: { state: "signature_failed", signatureFailureReason: "invalid_signature", ...content }, kind: "encrypted" };
+        }
+        const { failure, trusted, signer, acceptedSigner } = await checkSigner(parsed.signerCertificateDer, parsed.protectedHeaders, parsed.protectedHeaderFields, false);
+        if (failure) {
+            return { result: { state: "signature_failed", signatureFailureReason: failure, ...content, ...(failure === "signer_key_changed" ? acceptedSigner : signer) }, kind: "encrypted" };
+        }
+        return { result: { state: trusted ? "encrypted_verified" : "encrypted_unverified_signer", ...content, ...acceptedSigner }, kind: "encrypted" };
+    }
+    return { result: { state: "unprotected" }, kind: "other" };
+}
+const LIVE_VERIFIED_STATES = ["signed_verified", "encrypted_verified"];
+/** Whether a live result failed only because of the signer key's status - the cases a seal may override. Every other
+ * failure (an invalid signature, identity or header mismatch, `untrusted_signer`, HP-Outer tampering) never is. */
+function failedOnlyOnKeyStatus(result) {
+    if (result.headerTamperDetected) {
+        return false;
+    }
+    return (result.state === "signed_unverified_signer" ||
+        result.state === "encrypted_unverified_signer" ||
+        (result.state === "signature_failed" && result.signatureFailureReason === "signer_key_changed"));
+}
+/**
+ * `evaluateMessageSecurity()` with verification seals (`verificationSeal.ts`). The live evaluation always runs first,
+ * with the same arguments; then:
+ *
+ * **Live verified** (`"signed_verified"`/`"encrypted_verified"`, no HP-Outer tampering), and either no seal opens for this
+ * mailbox, message, raw MIME and `options.masterKeyGeneration`, or `options.sealGeneration` is older than
+ * `options.masterKeyGeneration`: the result gains `sealToWrite` (`{ seal, masterKeyGeneration }`), sealing the live
+ * `signerFingerprint` and state at `options.now` under the current generation. The caller persists it best effort
+ * (`setMessageVerificationSeal()`). This is how messages are re-sealed, lazily, after a `rekey()`: seals are never
+ * carried across a master key rotation (see `verificationSeal.ts`).
+ *
+ * **Live failure caused only by key status** (`signer_key_changed`, `signed_unverified_signer`,
+ * `encrypted_unverified_signer` - which also covers a signer key since revoked, since `signingKeyFingerprints()` drops
+ * such pins): when the seal opens, its `signerFingerprint` equals the live one and its state matches the message kind
+ * (signed-only vs. encrypted), the result is `"verified_at_first_open"` with `verifiedAt`, `sealedState`,
+ * `signerFingerprint`, the recovered content (for a signed-only `signer_key_changed` message too), `liveState`,
+ * `liveSignatureFailureReason` and `laterCompromised` (see `VerificationSealOptions.signerKeys`).
+ * `signatureFailureReason` is dropped.
+ *
+ * **Everything else** returns the live result unchanged: an invalid signature, identity or header mismatch,
+ * `untrusted_signer`, HP-Outer tampering, a seal whose MAC fails or whose hash, uids, generation or signer fingerprint differ, and
+ * every unsigned state.
+ *
+ * With `unlocked` undefined (no master key) the seal is ignored and no seal is built. Throws `KeysLockedError` when
+ * `unlocked` was destroyed (`keySession.ts`), before evaluating anything, or if it is destroyed while sealing; otherwise
+ * never throws - a seal that can't be built (e.g. uids too long for the size limit) just leaves `sealToWrite` unset.
+ */
+export async function evaluateMessageSecurityWithSeal(rawMime, unlocked, pinnedSignerFingerprints, readerAddress, options) {
+    if (unlocked?.destroyed) {
+        throw new KeysLockedError();
+    }
+    const live = await evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress);
+    const { result } = live;
+    const isLiveVerified = LIVE_VERIFIED_STATES.includes(result.state) && !result.headerTamperDetected;
+    // Every verified and key-status result carries the signer fingerprint (a certificate was always resolved).
+    if (!unlocked || !result.signerFingerprint || (!isLiveVerified && !failedOnlyOnKeyStatus(result))) {
+        return result;
+    }
+    const rawSha256 = await rawMimeSha256(rawMime);
+    const generation = options.masterKeyGeneration;
+    const opened = options.seal ? await openVerificationSeal(options.mailboxUid, unlocked, options.messageUid, options.seal, rawSha256, generation) : undefined;
+    const signerFingerprint = result.signerFingerprint.toLowerCase();
+    if (isLiveVerified) {
+        const storedSealIsOlder = options.sealGeneration !== undefined && options.sealGeneration < generation;
+        if (opened && !storedSealIsOlder) {
+            return result;
+        }
+        try {
+            const seal = await buildVerificationSeal(options.mailboxUid, unlocked, {
+                messageUid: options.messageUid,
+                rawSha256,
+                signerFingerprint,
+                state: result.state,
+                verifiedAt: options.now ?? Date.now(),
+                masterKeyGeneration: generation,
+            });
+            return { ...result, sealToWrite: { seal, masterKeyGeneration: generation } };
+        }
+        catch (err) {
+            if (err instanceof KeysLockedError) {
+                throw err;
+            }
+            return result;
+        }
+    }
+    const expectedSealedState = live.kind === "signed" ? "signed_verified" : "encrypted_verified";
+    if (!opened || opened.signerFingerprint !== signerFingerprint || opened.state !== expectedSealedState) {
+        return result;
+    }
+    const laterCompromised = (options.signerKeys ?? []).some((key) => key.fingerprint.toLowerCase() === signerFingerprint && !isTrustedForVerification(key));
+    const { signatureFailureReason, ...rest } = result;
+    return {
+        ...live.signedContent,
+        ...rest,
+        state: "verified_at_first_open",
+        verifiedAt: opened.verifiedAt,
+        sealedState: opened.state,
+        liveState: result.state,
+        ...(signatureFailureReason ? { liveSignatureFailureReason: signatureFailureReason } : {}),
+        ...(laterCompromised ? { laterCompromised: true } : {}),
+    };
+}

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

@@ -0,0 +1,143 @@
+/**
+ * A small, dependency-free MIME (RFC 5322 / RFC 2045-2047) parser used by `smimeMessage.ts` and
+ * `messageSecurity.ts` to read *received* messages - which, unlike this package's own output, can come
+ * from any foreign MUA/MTA. It deliberately covers exactly what S/MIME evaluation needs and nothing more:
+ *
+ * header unfolding (RFC 5322 §2.2.3) and CRLF-or-bare-LF line endings; case-insensitive RFC 2045
+ * `type/subtype; name=value` parameters, quoted or unquoted; RFC 2046 multipart splitting with
+ * preamble/epilogue, transport padding after the delimiter, and delimiters only recognized at the start
+ * of a line; `Content-Transfer-Encoding` decoding (base64, quoted-printable; 7bit/8bit/binary pass
+ * through) plus `charset` decoding via `TextDecoder`; and picking the displayable body (text/html
+ * preferred, text/plain otherwise) out of a nested multipart.
+ *
+ * **Binary strings.** Received message source is handled as a "binary string": one UTF-16 code unit per
+ * byte (0x00-0xFF), which is what `mailApi.ts`'s `getMessageRawContent()` returns (it reads the response
+ * as bytes and decodes them as Latin-1) and what decrypted CMS content is converted to. That keeps an
+ * 8bit body's bytes intact until its own `charset` is known, and keeps signed bytes verifiable exactly.
+ * A string containing any code unit above 0xFF can't be a binary string, so it is treated as already
+ * decoded text and UTF-8 encoded wherever bytes are needed (the pre-round-4 convention) - see
+ * `binaryStringToBytes()`.
+ *
+ * Not supported (documented, not silently wrong): RFC 2231 parameter continuations/charset-encoded
+ * parameters - not needed to classify, decrypt, or verify a message, and left verbatim. RFC 2047
+ * encoded-words are decoded only where text is shown to a user (`decodeHeaderText()`); raw header values
+ * (`MimeEntity.headers`) stay verbatim so header comparisons remain exact.
+ */
+/** One header field, unfolded, with its name exactly as written and its value trimmed. */
+export interface MimeHeaderField {
+    name: string;
+    value: string;
+}
+export interface MimeEntity {
+    /** Every header field in order - including repeated names (e.g. RFC 9788 `HP-Outer`). */
+    fields: MimeHeaderField[];
+    /** Lowercased name -> value of that name's FIRST occurrence. */
+    headers: Record<string, string>;
+    /** The raw, still-folded header block text (everything before the blank separator line). */
+    rawHeaderBlock: string;
+    /** The raw, undecoded body (everything after the blank separator line). */
+    body: string;
+}
+export interface ParameterizedHeader {
+    /** The lowercased main value (e.g. `multipart/signed`). */
+    value: string;
+    /** Lowercased parameter name -> unquoted value. */
+    params: Record<string, string>;
+}
+/** Splits a MIME entity into its header fields and body. Never throws. */
+export declare function parseMimeEntity(entity: string): MimeEntity;
+/** Parses an RFC 2045 parameterized header value (`Content-Type`, `Content-Disposition`). */
+export declare function parseParameterizedHeader(headerValue: string | undefined): ParameterizedHeader;
+/**
+ * Splits a multipart body on `boundary` per RFC 2046 §5.1.1: a delimiter is `--boundary` at the start of
+ * a line (optionally followed by transport-padding whitespace), the CRLF preceding it belongs to the
+ * delimiter (not the previous part), text before the first delimiter is preamble and text after the close
+ * delimiter (`--boundary--`) is epilogue - both discarded. Each returned part is the exact text between
+ * delimiter lines, which is what a `multipart/signed` signature covers.
+ */
+export declare function splitMultipart(body: string, boundary: string): string[];
+/** Decodes a base64 body into bytes, ignoring whitespace/line breaks. Returns `undefined` for invalid
+ * base64 rather than throwing. */
+export declare function decodeBase64Text(text: string): Uint8Array | undefined;
+/** `true` when every code unit of `value` is at most 0xFF - i.e. it can be a binary string (see this
+ * module's doc comment). */
+export declare function isBinaryString(value: string): boolean;
+/** Converts a binary string to its bytes, or - for a string that can't be one (a code unit above 0xFF) -
+ * to its UTF-8 encoding. */
+export declare function binaryStringToBytes(value: string): Uint8Array;
+/** Converts bytes to a binary string (one code unit per byte), in chunks so a large message never exceeds
+ * the engine's argument-count limit. */
+export declare function bytesToBinaryString(bytes: Uint8Array): string;
+/** Decodes a quoted-printable body (RFC 2045 §6.7) into bytes, in one linear pass into a preallocated
+ * buffer. Literal text between escapes (which can't legally be non-ASCII in QP, but is after an
+ * 8-bit-unsafe gateway) is written run by run, decided once for the whole input: as the runs' own bytes
+ * when the input is a binary string, else as their UTF-8 encoding (so an already-decoded `é` next to an
+ * emoji isn't written as a lone 0xE9 byte). A run always ends at an ASCII `=`, so a surrogate pair is never
+ * split. */
+export declare function decodeQuotedPrintable(text: string): Uint8Array;
+/** Decodes an entity's body into bytes per its `Content-Transfer-Encoding`. 7bit/8bit/binary (or no
+ * header) return the body's own bytes (see `binaryStringToBytes()`). Returns `undefined` only for invalid
+ * base64. */
+export declare function decodeBodyBytes(entity: MimeEntity): Uint8Array | undefined;
+/** Decodes an entity's body to text: transfer encoding first, then its `charset` parameter (UTF-8 when
+ * absent). A 7bit/8bit/binary body that isn't a binary string was already decoded by whoever produced the
+ * string and passes through unchanged; so does a binary-string body whose bytes are invalid in its charset
+ * (e.g. legacy already-decoded Latin-1 text under a UTF-8 charset). */
+export declare function decodeBodyText(entity: MimeEntity): string;
+/**
+ * Turns a raw header value into display text: a binary string holding valid UTF-8 (a raw 8-bit header,
+ * RFC 6532) is decoded as UTF-8, then RFC 2047 encoded-words (`=?charset?B|Q?text?=`) are decoded, with
+ * whitespace between adjacent encoded-words dropped (RFC 2047 §6.2). An encoded-word with an unknown
+ * charset or undecodable content is left verbatim.
+ */
+export declare function decodeHeaderText(value: string): string;
+/** Makes an unstructured header value (e.g. `Subject`) safe to serialize: CR/LF/NUL become a space
+ * (never a header break), and a value containing non-ASCII is RFC 2047-encoded. */
+export declare function encodeUnstructuredHeaderValue(value: string): string;
+/**
+ * Makes an address-list header value (`From`/`To`/`Cc`) safe to serialize: CR/LF/NUL become a space, and
+ * each mailbox's non-ASCII display name (`Zoë <z@example.com>`, quoted or not) is RFC 2047-encoded while
+ * its addr-spec is kept verbatim (an internationalized address is left to SMTPUTF8, never encoded -
+ * RFC 2047 §5 forbids encoded-words in an addr-spec). RFC 5322 group syntax (`Équipe: Zoë <z@x>, b@x;`)
+ * keeps its `:` and `;`, with the group label encoded as a phrase of its own. A top-level `:` only opens
+ * a group when a `;` follows it, so a stray colon in an unquoted display name isn't mistaken for one.
+ */
+export declare function encodeAddressListHeaderValue(value: string): string;
+/** A message's displayable content: `html` only for a real `text/html` part, `text` only for a
+ * `text/plain` part - never plain text mislabeled as HTML. */
+export interface DisplayBody {
+    html?: string;
+    text?: string;
+}
+/** Picks the displayable body out of an entity: a `text/html` part is preferred over `text/plain`, and a
+ * multipart entity is searched (non-attachment children only, bounded depth). Entities with no
+ * Content-Type default to text/plain per RFC 2045 §5.2. */
+export declare function extractDisplayBody(entity: MimeEntity, depth?: number): DisplayBody;
+/** One attachment found inside a MIME entity (see `extractAttachments()`). */
+export interface MimeAttachment {
+    /** The `Content-Disposition` `filename` (else the `Content-Type` `name`), RFC 2047-decoded; absent if neither. */
+    filename?: string;
+    /** The lowercased MIME type, e.g. `application/pdf`. */
+    contentType: string;
+    /** `"attachment"` for `Content-Disposition: attachment`, `"inline"` otherwise (an inline image, or a part with a
+     * filename and no disposition). */
+    disposition: "attachment" | "inline";
+    /** The `Content-ID` without its angle brackets, if any - how an HTML body references an inline part. */
+    contentId?: string;
+    /** Decodes the part's content (transfer encoding undone) - lazily, so evaluating a message never pays for
+     * attachments nobody opens. `undefined` for invalid base64. */
+    decode(): Uint8Array | undefined;
+}
+/**
+ * Lists the attachments inside `entity` (descending into multipart children, bounded depth): every leaf part
+ * with `Content-Disposition: attachment`, a filename, or a non-text type. The `text/plain`/`text/html` parts a
+ * reader would display (no disposition, no filename) are not attachments. Nested `message/rfc822` content is
+ * reported as one attachment, never expanded.
+ */
+export declare function extractAttachments(entity: MimeEntity, depth?: number): MimeAttachment[];
+/** HTML-escapes plain text and wraps it in a whitespace-preserving `<pre>`, so a `text/plain` body can be
+ * rendered through the same HTML path without ever being interpreted as markup. */
+export declare function plainTextToHtml(text: string): string;
+/** Extracts the bare, lowercased addr-specs from an address-list header value (`"Name" <a@b>, c@d`).
+ * Handles quoted display names containing commas/angle brackets and RFC 5322 comments. */
+export declare function extractAddresses(headerValue: string | undefined): string[];