@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/crypto/verificationSeal.js

@@ -0,0 +1,220 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Verification seals: a client-side record that a message's signature verified when it was first opened, so later key
+ * events (a signer key replaced beyond the retained previous keys, a deleted contact, expiry, a later compromise
+ * revocation) don't make it look untrusted. See `messageSecurity.ts`'s `evaluateMessageSecurityWithSeal()` for how a
+ * seal is used.
+ *
+ * A seal is an HMAC-SHA256 over the verification result, keyed by a per-mailbox key HKDF-derived from the unlocked
+ * master key - so the server, which stores it as the opaque `Message.verificationSeal` (`mailApi.ts`'s
+ * `setMessageVerificationSeal()`), can't forge or alter one. The seal key is derived on each call (the same way
+ * web-client's local search index key is: `hkdfDerive()` with a fixed salt and a mailbox-bound label), imported as a
+ * non-extractable `CryptoKey`, its raw bytes zeroed at once, and never cached or persisted - there is nothing to destroy
+ * beyond the master key `keySession.ts`'s `destroyUnlockedKeys()` already zeroes. A destroyed `UnlockedKeys` object
+ * throws `KeysLockedError` (checked on entry and again after the derivation awaits).
+ *
+ * **Format (v1).** `v1.<base64url(JSON payload)>.<base64url(32-byte HMAC-SHA256 tag)>`, where the payload is
+ * `{ "v": 1, "mb": mailboxUid, "id": messageUid, "g": masterKeyGeneration, "h": rawSha256, "fp": signerFingerprint,
+ * "st": state, "t": verifiedAt }` (`h`/`fp` lowercased hex). The tag is not computed over the JSON text: it covers a canonical encoding of the fields
+ * (see `canonicalBytes()`), so the JSON's own formatting carries no meaning. Every character is in restapi's allowed
+ * `[A-Za-z0-9+/=_.:-]`, and a seal is at most `MAX_VERIFICATION_SEAL_LENGTH` (2048) characters.
+ *
+ * **Master key rotation.** A seal is bound to the vault's `masterKeyGeneration` (`keyvaultApi.ts`'s
+ * `KeyVault.masterKeyGeneration`): the generation is MAC-covered, and `openVerificationSeal()` refuses a seal for a
+ * generation other than the expected one. Seals are deliberately not carried across a `rekey()`: a seal from an older
+ * generation never opens under the new master key (its MAC fails too), so a rotation after a suspected compromise can't
+ * bless seals that someone holding the old master key could have written. Such a message shows its live result until its
+ * next successful live verification, when `evaluateMessageSecurityWithSeal()` re-seals it lazily under the current
+ * generation (the server replaces a stored seal only for a newer, current generation).
+ */
+import { fromBase64Url, toBase64Url } from "./encoding.js";
+import { KeysLockedError, hkdfDerive } from "./masterKey.js";
+import { binaryStringToBytes } from "./mime.js";
+/** The longest seal restapi stores (`Message.verificationSeal`). */
+export const MAX_VERIFICATION_SEAL_LENGTH = 2048;
+/** The characters restapi allows in a seal. */
+export const VERIFICATION_SEAL_CHARSET = /^[A-Za-z0-9+/=_.:-]*$/;
+/** The HKDF label the seal key is derived under (suffixed with `:<mailboxUid>`). */
+export const VERIFICATION_SEAL_HKDF_LABEL = "rapidmx:verification-seal:v1";
+/** Fixed, non-secret HKDF salt: the master key is already uniformly random (see web-client's `localIndexKey.ts`). */
+const FIXED_SALT = new TextEncoder().encode("rapidmx-verification-seal-v1");
+const SEAL_VERSION = "v1";
+const TAG_LENGTH_BYTES = 32;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const SEALED_STATES = ["signed_verified", "encrypted_verified"];
+/** SHA-256 (lowercase hex) of a message's raw MIME, as `evaluateMessageSecurity()` receives it: a binary string
+ * (`mailApi.ts`'s `getMessageRawContent()`, one code unit per byte) or the bytes themselves. A string that can't be a
+ * binary string (a code unit above 0xFF) is hashed as its UTF-8 encoding, like `mime.ts`'s `binaryStringToBytes()`. */
+export async function rawMimeSha256(raw) {
+    const bytes = typeof raw === "string" ? binaryStringToBytes(raw) : raw;
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function assertNotDestroyed(unlocked) {
+    if (unlocked.destroyed) {
+        throw new KeysLockedError();
+    }
+}
+/** Derives the mailbox's seal key and imports it as a non-extractable HMAC key, zeroing the raw bytes. Throws
+ * `KeysLockedError` for destroyed or zeroed key material. */
+async function importSealKey(mailboxUid, unlocked) {
+    assertNotDestroyed(unlocked);
+    const raw = await hkdfDerive(unlocked.masterKey, FIXED_SALT, `${VERIFICATION_SEAL_HKDF_LABEL}:${mailboxUid}`);
+    try {
+        const key = await crypto.subtle.importKey("raw", raw, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        // Locked while deriving: the derivation may have copied the master key before it was zeroed.
+        assertNotDestroyed(unlocked);
+        return key;
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+/** Length-prefixed (4-byte big-endian) UTF-8 fields, so no two field lists encode alike. */
+function canonicalBytes(fields) {
+    const encoded = fields.map((field) => new TextEncoder().encode(field));
+    const out = new Uint8Array(encoded.reduce((total, bytes) => total + 4 + bytes.length, 0));
+    const view = new DataView(out.buffer);
+    let offset = 0;
+    for (const bytes of encoded) {
+        view.setUint32(offset, bytes.length);
+        out.set(bytes, offset + 4);
+        offset += 4 + bytes.length;
+    }
+    return out;
+}
+async function computeTag(key, fields) {
+    const data = canonicalBytes([
+        SEAL_VERSION,
+        fields.mailboxUid,
+        fields.messageUid,
+        String(fields.masterKeyGeneration),
+        fields.rawSha256,
+        fields.signerFingerprint,
+        fields.state,
+        String(fields.verifiedAt),
+    ]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", key, data));
+}
+/** Compares every byte whatever the first difference (callers only pass 32-byte tags; a length difference still fails). */
+function constantTimeEqual(a, b) {
+    let diff = a.length ^ b.length;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+/** A non-negative safe integer - a `verifiedAt` or a `masterKeyGeneration`. */
+function isValidTimestamp(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * Seals a verification result for `mailboxUid`'s message `input.messageUid` - see this module's doc comment for the
+ * format. Throws `KeysLockedError` for destroyed keys, and a plain `Error` for input that can't be sealed: empty uids or
+ * fingerprint, a `rawSha256` that isn't 64 hex digits, an unknown `state`, a `verifiedAt` or `masterKeyGeneration` that isn't a non-negative
+ * integer, or a seal that would exceed `MAX_VERIFICATION_SEAL_LENGTH` (very long uids).
+ */
+export async function buildVerificationSeal(mailboxUid, unlocked, input) {
+    const fields = {
+        mailboxUid,
+        messageUid: input.messageUid,
+        rawSha256: typeof input.rawSha256 === "string" ? input.rawSha256.toLowerCase() : "",
+        signerFingerprint: typeof input.signerFingerprint === "string" ? input.signerFingerprint.toLowerCase() : "",
+        state: input.state,
+        verifiedAt: input.verifiedAt,
+        masterKeyGeneration: input.masterKeyGeneration,
+    };
+    if (!mailboxUid || !fields.messageUid || !fields.signerFingerprint) {
+        throw new Error("A verification seal needs a mailbox uid, message uid and signer fingerprint.");
+    }
+    if (!SHA256_HEX.test(fields.rawSha256)) {
+        throw new Error("A verification seal's rawSha256 must be a hex SHA-256 digest.");
+    }
+    if (!SEALED_STATES.includes(fields.state) || !isValidTimestamp(fields.verifiedAt) || !isValidTimestamp(fields.masterKeyGeneration)) {
+        throw new Error("A verification seal needs a verified state and non-negative integer verifiedAt and masterKeyGeneration.");
+    }
+    const key = await importSealKey(mailboxUid, unlocked);
+    const payload = { v: 1, mb: fields.mailboxUid, id: fields.messageUid, g: fields.masterKeyGeneration, h: fields.rawSha256, fp: fields.signerFingerprint, st: fields.state, t: fields.verifiedAt };
+    const payloadText = toBase64Url(new TextEncoder().encode(JSON.stringify(payload)));
+    const seal = `${SEAL_VERSION}.${payloadText}.${toBase64Url(await computeTag(key, fields))}`;
+    if (seal.length > MAX_VERIFICATION_SEAL_LENGTH) {
+        throw new Error(`A verification seal can't exceed ${MAX_VERIFICATION_SEAL_LENGTH} characters.`);
+    }
+    return seal;
+}
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+/** Splits and decodes a v1 seal, or `undefined` for anything malformed. Never throws. */
+function parseSeal(seal) {
+    if (typeof seal !== "string" || seal.length > MAX_VERIFICATION_SEAL_LENGTH || !VERIFICATION_SEAL_CHARSET.test(seal)) {
+        return undefined;
+    }
+    const parts = seal.split(".");
+    if (parts.length !== 3 || parts[0] !== SEAL_VERSION || !BASE64URL.test(parts[1]) || !BASE64URL.test(parts[2])) {
+        return undefined;
+    }
+    try {
+        const tag = fromBase64Url(parts[2]);
+        const payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(fromBase64Url(parts[1])));
+        if (tag.length !== TAG_LENGTH_BYTES || typeof payload !== "object" || payload === null) {
+            return undefined;
+        }
+        const { v, mb, id, g, h, fp, st, t } = payload;
+        if (v !== 1 ||
+            typeof mb !== "string" ||
+            typeof id !== "string" ||
+            !isValidTimestamp(g) ||
+            typeof h !== "string" ||
+            !SHA256_HEX.test(h) ||
+            typeof fp !== "string" ||
+            !fp ||
+            typeof st !== "string" ||
+            !SEALED_STATES.includes(st) ||
+            !isValidTimestamp(t)) {
+            return undefined;
+        }
+        return { fields: { mailboxUid: mb, messageUid: id, rawSha256: h, signerFingerprint: fp, state: st, verifiedAt: t, masterKeyGeneration: g }, tag };
+    }
+    catch {
+        // Invalid base64 or UTF-8, or JSON that won't parse.
+        return undefined;
+    }
+}
+/**
+ * Opens a seal written by `buildVerificationSeal()`. Resolves `{ signerFingerprint, state, verifiedAt, masterKeyGeneration }`
+ * only when the version is known, the tag verifies (constant-time comparison) under this mailbox's seal key, the sealed mailbox and
+ * message uids equal `mailboxUid`/`messageUid`, and the sealed hash equals `rawSha256` (the current raw MIME's
+ * `rawMimeSha256()`), and - when `expectedMasterKeyGeneration` is given - the sealed generation equals it (the vault's
+ * current `masterKeyGeneration`; a seal from another generation wouldn't open under that master key anyway, but this
+ * checks it explicitly). Anything else - a malformed, truncated, tampered, foreign or oversized seal, or a seal sealed
+ * under a different master key - resolves `undefined`; this never throws for the seal's content. Throws
+ * `KeysLockedError` for destroyed keys, whatever the seal.
+ */
+export async function openVerificationSeal(mailboxUid, unlocked, messageUid, seal, rawSha256, expectedMasterKeyGeneration) {
+    assertNotDestroyed(unlocked);
+    const parsed = parseSeal(seal);
+    if (!parsed) {
+        return undefined;
+    }
+    const key = await importSealKey(mailboxUid, unlocked);
+    // The tag is computed over the values the caller expects, so a seal for another mailbox or message fails the MAC as
+    // well as the explicit comparison below.
+    const expected = await computeTag(key, { ...parsed.fields, mailboxUid, messageUid });
+    const { fields } = parsed;
+    const tagMatches = constantTimeEqual(expected, parsed.tag);
+    if (!tagMatches ||
+        fields.mailboxUid !== mailboxUid ||
+        fields.messageUid !== messageUid ||
+        fields.rawSha256 !== String(rawSha256).toLowerCase() ||
+        (expectedMasterKeyGeneration !== undefined && fields.masterKeyGeneration !== expectedMasterKeyGeneration)) {
+        return undefined;
+    }
+    return {
+        signerFingerprint: fields.signerFingerprint,
+        state: fields.state,
+        verifiedAt: fields.verifiedAt,
+        masterKeyGeneration: fields.masterKeyGeneration,
+    };
+}

package/dist/lib/mail/compose/composeQuoting.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Builds what a Reply/Reply All/Forward compose starts with - its recipients, its quoted original message, and the
+ * body layout around the quote - entirely client-side, same "restapi never composes message bodies" convention as
+ * `mailApi.ts`'s `assembleDraft()`.
+ *
+ * The quote carries the original's full body, as the reader saw it: the caller passes a `QuotedBody` (the message's
+ * sanitized HTML body, its decrypted/verified content, or its plain-text body). HTML is sanitized again here with
+ * the same remote-resource-stripping policy used to display a client-rendered body (`messageBodySanitizer.ts`), plus
+ * a stricter tag list for the editor. `message.bodyPreview` - a server-derived excerpt, truncated - is only the last
+ * resort, when no body could be loaded.
+ */
+import { Message, Recipient } from "../mailApi.js";
+/**
+ * A recipient's display name, without the address the server sometimes leaves in it: an ingested message's `from`
+ * carries the whole `"Bob Allen" <bob@example.com>` From header as its display name, which would otherwise be shown
+ * (and addressed) as `"Bob Allen" <bob@example.com> <bob@example.com>`. A name that is, or ends in, the recipient's
+ * own address is reduced to the part before it; a name that is any other address is dropped entirely.
+ */
+export declare function recipientDisplayName(recipient: Recipient): string | undefined;
+/** The body of the message being quoted, as loaded by the caller. `html` is preferred over `text`; either may be
+ * absent (e.g. an encrypted message this device can't open, or a failed fetch). */
+export interface QuotedBody {
+    /** An HTML body. Sanitized again by the quote builders, so it may come from any source. */
+    html?: string;
+    /** A plain-text body. HTML-escaped by the quote builders. */
+    text?: string;
+}
+/** Prepends "Re: " unless `subject` already starts with it (any casing) — the same convention every
+ * mail client uses to avoid a "Re: Re: Re: ..." chain. */
+export declare function replySubject(subject: string): string;
+/** Same convention as `replySubject()`, for forwards. */
+export declare function forwardSubject(subject: string): string;
+/** The quoted original a Reply/Reply All compose starts with: an "On <date>, Name <address> wrote:" line and the
+ * original body in a blockquote. `buildComposeBodyHtml()` places it in the body. */
+export declare function buildReplyQuote(message: Message, body?: QuotedBody): string;
+/** The quoted body a Forward compose starts with — includes the original headers block, matching every
+ * major mail client's own forward convention, since a forward (unlike a reply) has no visible reply
+ * chain of its own to imply who originally sent it. */
+export declare function buildForwardQuote(message: Message, body?: QuotedBody): string;
+/**
+ * The HTML a compose body starts with, laid out the way Outlook and Gmail do: an empty paragraph first (where the
+ * caret goes, so typing lands above everything else), then the signature, then a blank line, then the quoted
+ * original. `""` when there is neither a signature nor a quote, which leaves the editor's own single empty
+ * paragraph.
+ *
+ * A quote is always preceded by an empty paragraph of its own, on top of the one that separates it from a
+ * signature: what the reply opens with is the caret's line and then the quote right underneath it, and there has to
+ * be somewhere to press Enter into above the "On ... wrote:" line without first making room for it by hand.
+ */
+export declare function buildComposeBodyHtml(signatureHtml?: string, quotedHtml?: string): string;
+/**
+ * The longest `References` chain `buildReplyThreading()` reports. A chain grows by one entry per reply forever
+ * and the server trims what it actually writes into the header anyway; sending an unbounded one is pointless.
+ * The root is always kept - it is what a conversation is keyed on - and the oldest entries after it are dropped.
+ */
+export declare const MAX_REPLY_REFERENCES = 20;
+/**
+ * What a reply or forward must record about the thread it continues, from the message it is a reply to: the
+ * RFC 5322 `In-Reply-To` (that message's own `messageId`) and the `References` chain (its own chain, with its
+ * `messageId` appended). Pass the result to `createDraft()`.
+ *
+ * Without it a reply is relayed with no threading headers at all - this server composes a reply's MIME from the
+ * structured compose input, which says nothing about what is being replied to - so every recipient's mail server,
+ * and the sender's own Sent Items copy, files it as a brand-new conversation instead of adding it to the thread.
+ */
+export declare function buildReplyThreading(message: Pick<Message, "messageId" | "references">): {
+    inReplyTo: string;
+    references: string[];
+};
+/** The To and Cc a reply starts with. */
+export interface ReplyRecipients {
+    to: Recipient[];
+    cc: Recipient[];
+}
+/**
+ * Who a Reply or Reply All goes to. The replying mailbox itself (`ownAddresses`: its primary address and aliases,
+ * compared case-insensitively) is left out, and no address is repeated.
+ *
+ * A reply to someone else's message goes to its sender. Reply All adds the original To recipients to To and the
+ * original Cc recipients to Cc.
+ *
+ * A reply to a message the mailbox sent itself (e.g. from Sent Items) goes to the original To recipients instead of
+ * back to the mailbox, and Reply All keeps the original Cc as Cc. With no other To recipient, the original Cc
+ * recipients become To. Only a message the mailbox sent to nobody but itself is replied to itself.
+ *
+ * Bcc recipients are never carried over. Display names are kept.
+ */
+export declare function buildReplyRecipients(message: Message, ownAddresses: string[], replyAll: boolean): ReplyRecipients;

package/dist/lib/mail/compose/composeQuoting.js

@@ -0,0 +1,204 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Builds what a Reply/Reply All/Forward compose starts with - its recipients, its quoted original message, and the
+ * body layout around the quote - entirely client-side, same "restapi never composes message bodies" convention as
+ * `mailApi.ts`'s `assembleDraft()`.
+ *
+ * The quote carries the original's full body, as the reader saw it: the caller passes a `QuotedBody` (the message's
+ * sanitized HTML body, its decrypted/verified content, or its plain-text body). HTML is sanitized again here with
+ * the same remote-resource-stripping policy used to display a client-rendered body (`messageBodySanitizer.ts`), plus
+ * a stricter tag list for the editor. `message.bodyPreview` - a server-derived excerpt, truncated - is only the last
+ * resort, when no body could be loaded.
+ */
+import { sanitizeQuotedHtml } from "../messageBodySanitizer.js";
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function textToHtml(text) {
+    return escapeHtml(text)
+        .split(/\r?\n/)
+        .map((line) => `<p>${line || "&nbsp;"}</p>`)
+        .join("");
+}
+/**
+ * A recipient's display name, without the address the server sometimes leaves in it: an ingested message's `from`
+ * carries the whole `"Bob Allen" <bob@example.com>` From header as its display name, which would otherwise be shown
+ * (and addressed) as `"Bob Allen" <bob@example.com> <bob@example.com>`. A name that is, or ends in, the recipient's
+ * own address is reduced to the part before it; a name that is any other address is dropped entirely.
+ */
+export function recipientDisplayName(recipient) {
+    const name = recipient.displayName?.trim();
+    if (!name) {
+        return undefined;
+    }
+    const angle = /^(.*)<([^<>]*)>$/.exec(name);
+    const inner = angle ? angle[2].trim() : name;
+    if (!inner.includes("@")) {
+        return name;
+    }
+    if (inner.toLowerCase() !== recipient.address.trim().toLowerCase()) {
+        return undefined;
+    }
+    const before = (angle ? angle[1] : "").trim().replace(/^"(.*)"$/s, "$1").trim();
+    return before || undefined;
+}
+/** The same recipient with `recipientDisplayName()`'s cleaned-up name (absent when nothing is left of it). */
+function cleaned(recipient) {
+    const name = recipientDisplayName(recipient);
+    return name === recipient.displayName ? recipient : { ...recipient, ...(name ? { displayName: name } : { displayName: undefined }) };
+}
+/** `Name <address>`, or the bare address when there's no usable display name. */
+function nameAndAddress(recipient) {
+    const name = recipientDisplayName(recipient);
+    return name ? `${name} <${recipient.address}>` : recipient.address;
+}
+const QUOTE_STYLE = "border-left:2px solid #ccc;margin:0;padding-left:1em;color:#666;";
+/** Whether sanitized HTML still shows anything: text other than whitespace, or an image. */
+function hasVisibleContent(html) {
+    return /<img\b/i.test(html) || html.replace(/<[^>]*>/g, "").replace(/&nbsp;|\s/g, "") !== "";
+}
+/** The quoted content: the sanitized HTML body, else the text body, else the body preview. */
+function quotedContent(message, body) {
+    if (body?.html) {
+        const sanitized = sanitizeQuotedHtml(body.html);
+        if (hasVisibleContent(sanitized)) {
+            return sanitized;
+        }
+    }
+    if (body?.text?.trim()) {
+        return textToHtml(body.text);
+    }
+    return textToHtml(message.bodyPreview ?? "");
+}
+/** Prepends "Re: " unless `subject` already starts with it (any casing) — the same convention every
+ * mail client uses to avoid a "Re: Re: Re: ..." chain. */
+export function replySubject(subject) {
+    return /^re:/i.test(subject.trim()) ? subject : `Re: ${subject}`;
+}
+/** Same convention as `replySubject()`, for forwards. */
+export function forwardSubject(subject) {
+    return /^fwd:/i.test(subject.trim()) ? subject : `Fwd: ${subject}`;
+}
+/** The quoted original a Reply/Reply All compose starts with: an "On <date>, Name <address> wrote:" line and the
+ * original body in a blockquote. `buildComposeBodyHtml()` places it in the body. */
+export function buildReplyQuote(message, body) {
+    const when = new Date(message.receivedDate).toLocaleString();
+    return (`<p>On ${escapeHtml(when)}, ${escapeHtml(nameAndAddress(message.from))} wrote:</p>` +
+        `<blockquote style="${QUOTE_STYLE}">${quotedContent(message, body)}</blockquote>`);
+}
+/** The quoted body a Forward compose starts with — includes the original headers block, matching every
+ * major mail client's own forward convention, since a forward (unlike a reply) has no visible reply
+ * chain of its own to imply who originally sent it. */
+export function buildForwardQuote(message, body) {
+    const when = new Date(message.receivedDate).toLocaleString();
+    const to = message.recipients
+        .filter((r) => r.type === "to")
+        .map(nameAndAddress)
+        .join(", ");
+    return (`<p>---------- Forwarded message ----------<br>` +
+        `From: ${escapeHtml(nameAndAddress(message.from))}<br>` +
+        `Date: ${escapeHtml(when)}<br>` +
+        `Subject: ${escapeHtml(message.subject || "(no subject)")}<br>` +
+        `To: ${escapeHtml(to)}</p>` +
+        `<blockquote style="${QUOTE_STYLE}">${quotedContent(message, body)}</blockquote>`);
+}
+/**
+ * The HTML a compose body starts with, laid out the way Outlook and Gmail do: an empty paragraph first (where the
+ * caret goes, so typing lands above everything else), then the signature, then a blank line, then the quoted
+ * original. `""` when there is neither a signature nor a quote, which leaves the editor's own single empty
+ * paragraph.
+ *
+ * A quote is always preceded by an empty paragraph of its own, on top of the one that separates it from a
+ * signature: what the reply opens with is the caret's line and then the quote right underneath it, and there has to
+ * be somewhere to press Enter into above the "On ... wrote:" line without first making room for it by hand.
+ */
+export function buildComposeBodyHtml(signatureHtml, quotedHtml) {
+    if (!signatureHtml && !quotedHtml) {
+        return "";
+    }
+    const separator = signatureHtml && quotedHtml ? "<p></p>" : "";
+    const aboveQuote = quotedHtml ? "<p></p>" : "";
+    return `<p></p>${signatureHtml ?? ""}${separator}${aboveQuote}${quotedHtml ?? ""}`;
+}
+/**
+ * The longest `References` chain `buildReplyThreading()` reports. A chain grows by one entry per reply forever
+ * and the server trims what it actually writes into the header anyway; sending an unbounded one is pointless.
+ * The root is always kept - it is what a conversation is keyed on - and the oldest entries after it are dropped.
+ */
+export const MAX_REPLY_REFERENCES = 20;
+/**
+ * What a reply or forward must record about the thread it continues, from the message it is a reply to: the
+ * RFC 5322 `In-Reply-To` (that message's own `messageId`) and the `References` chain (its own chain, with its
+ * `messageId` appended). Pass the result to `createDraft()`.
+ *
+ * Without it a reply is relayed with no threading headers at all - this server composes a reply's MIME from the
+ * structured compose input, which says nothing about what is being replied to - so every recipient's mail server,
+ * and the sender's own Sent Items copy, files it as a brand-new conversation instead of adding it to the thread.
+ */
+export function buildReplyThreading(message) {
+    const parent = message.messageId.trim();
+    const chain = [];
+    for (const reference of message.references ?? []) {
+        const id = typeof reference === "string" ? reference.trim() : "";
+        if (id && id !== parent && !chain.includes(id)) {
+            chain.push(id);
+        }
+    }
+    chain.push(parent);
+    // Trimmed from after the root, so the thread's first message (what the conversation is keyed on) and the
+    // most recent ancestors both survive.
+    while (chain.length > MAX_REPLY_REFERENCES) {
+        chain.splice(1, 1);
+    }
+    return { inReplyTo: parent, references: chain };
+}
+/**
+ * Who a Reply or Reply All goes to. The replying mailbox itself (`ownAddresses`: its primary address and aliases,
+ * compared case-insensitively) is left out, and no address is repeated.
+ *
+ * A reply to someone else's message goes to its sender. Reply All adds the original To recipients to To and the
+ * original Cc recipients to Cc.
+ *
+ * A reply to a message the mailbox sent itself (e.g. from Sent Items) goes to the original To recipients instead of
+ * back to the mailbox, and Reply All keeps the original Cc as Cc. With no other To recipient, the original Cc
+ * recipients become To. Only a message the mailbox sent to nobody but itself is replied to itself.
+ *
+ * Bcc recipients are never carried over. Display names are kept.
+ */
+export function buildReplyRecipients(message, ownAddresses, replyAll) {
+    const own = new Set(ownAddresses.map((address) => address.trim().toLowerCase()));
+    const seen = new Set();
+    const take = (recipients) => recipients
+        .filter((recipient) => {
+        const key = recipient.address.trim().toLowerCase();
+        if (!key || own.has(key) || seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    })
+        .map(cleaned);
+    const originalTo = message.recipients.filter((r) => r.type === "to");
+    const originalCc = message.recipients.filter((r) => r.type === "cc");
+    if (!own.has(message.from.address.trim().toLowerCase())) {
+        const to = take([message.from, ...(replyAll ? originalTo : [])]);
+        return { to, cc: replyAll ? take(originalCc) : [] };
+    }
+    const to = take(originalTo);
+    const cc = take(originalCc);
+    if (to.length > 0) {
+        return { to, cc: replyAll ? cc : [] };
+    }
+    if (cc.length > 0) {
+        return { to: cc, cc: [] };
+    }
+    return { to: [cleaned(message.from)], cc: [] };
+}

package/dist/lib/mail/compose/emojiData.d.ts

@@ -0,0 +1,9 @@
+export interface EmojiCategory {
+    id: string;
+    emojis: {
+        id: string;
+        native: string;
+        name: string;
+    }[];
+}
+export declare const EMOJI_CATEGORIES: EmojiCategory[];

package/dist/lib/mail/compose/emojiData.js

@@ -0,0 +1,18 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Emoji data for the Compose window's "Insert emoji" picker — the full standard unicode emoji set
+ * (categories + native characters), sourced from `@emoji-mart/data` (used as a pure data file only;
+ * this app has its own grid UI rather than pulling in `@emoji-mart`'s full React picker component).
+ */
+import emojiData from "@emoji-mart/data" with { type: "json" };
+const data = emojiData;
+export const EMOJI_CATEGORIES = data.categories.map((category) => ({
+    id: category.id,
+    emojis: category.emojis
+        .map((emojiId) => data.emojis[emojiId])
+        .filter((emoji) => emoji != null && emoji.skins.length > 0)
+        .map((emoji) => ({ id: emoji.id, native: emoji.skins[0].native, name: emoji.name })),
+}));

package/dist/lib/mail/compose/giphyApi.d.ts

@@ -0,0 +1,17 @@
+/** Thin wrapper over this server's own Giphy search proxy (`src/routes/BaseGiphySearchRoute.ts`) —
+ * never calls Giphy directly from the browser, since that would require shipping the API key in the
+ * client bundle. See `GifPicker.tsx` for the UI this backs. */
+import { ApiClient } from "../../util/api.js";
+export interface GiphyGif {
+    id: string;
+    /** A small rendition, for the search grid's thumbnails. */
+    previewUrl: string;
+    /** The full-resolution GIF — inserted into the message body when chosen. */
+    url: string;
+    title: string;
+}
+/** An empty/blank `query` returns Giphy's trending feed (see the backend route's own doc comment). `client`,
+ * given here, is an explicit `ApiClient` from `createApiClient()` (e.g. one account of a multi-account app) to
+ * call instead of the default global `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`.
+ * Omitted (the default), this behaves exactly as before. */
+export declare function searchGifs(query: string, client?: ApiClient): Promise<GiphyGif[]>;

package/dist/lib/mail/compose/giphyApi.js

@@ -0,0 +1,20 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Thin wrapper over this server's own Giphy search proxy (`src/routes/BaseGiphySearchRoute.ts`) —
+ * never calls Giphy directly from the browser, since that would require shipping the API key in the
+ * client bundle. See `GifPicker.tsx` for the UI this backs. */
+import { withClient } from "../../util/api.js";
+/** An empty/blank `query` returns Giphy's trending feed (see the backend route's own doc comment). `client`,
+ * given here, is an explicit `ApiClient` from `createApiClient()` (e.g. one account of a multi-account app) to
+ * call instead of the default global `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`.
+ * Omitted (the default), this behaves exactly as before. */
+export function searchGifs(query, client) {
+    const params = new URLSearchParams();
+    const trimmed = query.trim();
+    if (trimmed) {
+        params.set("q", trimmed);
+    }
+    return withClient(client, `/mail/giphy/search?${params.toString()}`);
+}