@rapidmx/web-client 0.20.0 → 0.22.0

package/lib/contacts/contactsApi.ts

@@ -0,0 +1,289 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
+ * comment for the shared ACL/authorization model every wrapper file here follows. */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+import {
+    type EncryptionPreference,
+    type KeyConflict,
+    type PreviousKey,
+    type PublicKey,
+    type RejectedKey,
+    signingKeyFingerprints,
+} from "../crypto/keyvaultApi.js";
+
+export type ContactAddressKind = "home" | "work" | "other";
+
+export interface ContactEmail {
+    address: string;
+    type: ContactAddressKind;
+}
+
+export interface ContactPhone {
+    phoneNumber: string;
+    type: ContactAddressKind;
+}
+
+export interface ContactPostalAddress {
+    street?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+    type: ContactAddressKind;
+}
+
+export interface Contact {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    folderUid: string;
+    /** The `ContactList` (group) this contact belongs to, if any. */
+    contactListUid?: string;
+    displayName: string;
+    givenName?: string;
+    surname?: string;
+    emails: ContactEmail[];
+    phones: ContactPhone[];
+    addresses: ContactPostalAddress[];
+    company?: string;
+    jobTitle?: string;
+    notes?: string;
+    photoBlobKey?: string;
+    sourceUid?: string;
+    /** Whether the caller has starred/favorited this contact. Absent is equivalent to `false`. */
+    favorite?: boolean;
+    /** Free-form category labels (Outlook-style colored categories) applied to this contact, if any. */
+    categories?: string[];
+    /** Present (and `true`) only when fetched via `listDeletedContacts()` — a soft-deleted `RecoverableBaseEntity`
+     * record still exists server-side so it can be restored, per `@rapidmx/restapi`'s own soft-delete model. */
+    deleted?: boolean;
+    /** This contact's known encryption preference, per `specs/end-to-end_encryption.md` — discovered
+     * via `crypto/keyvaultApi.ts`'s `lookupKeys()` at compose time, never fetched on message receipt
+     * (that would leak read timing to the sender's server). */
+    encryptPreference?: EncryptionPreference;
+    /** This contact's pinned public keys. Trust is TOFU (trust-on-first-use) — see `keyConflicts` for what
+     * happens when a newly observed key differs from one of these. */
+    keys?: PublicKey[];
+    /** Observed keys that conflict with the currently pinned key of the same `useType`, at most one per `useType` —
+     * each blocks silent acceptance until the user resolves it (`keyvaultApi.ts`'s `resolveKeyConflict()`, the spec's
+     * Key Conflict Handling). The pinned `keys` are retained unchanged while a conflict is set. */
+    keyConflicts?: KeyConflict[];
+    /** Keys that were pinned before and replaced (by the user accepting a conflict, or by restapi's automatic
+     * same-issuer renewal of an expired or revoked key), newest first, at most 5 per `useType`. Signing keys here
+     * still count as trusted signers — see `signingKeyFingerprints()`. */
+    previousKeys?: PreviousKey[];
+    /** Keys the user rejected when resolving a conflict. */
+    rejectedKeys?: RejectedKey[];
+}
+
+/** Lists a folder's contacts, alphabetically by display name. Never includes soft-deleted contacts — see
+ * `listDeletedContacts()` for those. */
+export function listContacts(folderUid: string, params: ListParams = {}, client?: ApiClient): Promise<Contact[]> {
+    return withClient(client, `/mail/contacts?${buildQuery(params, { folderUid, sort: JSON.stringify({ displayName: "ASC" }) })}`);
+}
+
+function contactsMatching(contacts: Contact[], address: string): Contact[] {
+    const wanted = address.trim().toLowerCase();
+    return contacts.filter((contact) => contact.emails.some((email) => email.address.trim().toLowerCase() === wanted));
+}
+
+/** The trusted signing-key fingerprints of every contact in `contacts` with an email equal (case-insensitively) to
+ * `address`: each contact's pinned `keys` and its `previousKeys`, so mail signed before a key rotation still verifies -
+ * see `keyvaultApi.ts`'s `signingKeyFingerprints()` for the rules (expired and superseded keys kept, compromised or reasonless revoked keys excluded). De-duplicated;
+ * `[]` when no contact matches or none has a trusted signing key. */
+export function pinnedSigningFingerprintsFor(contacts: Contact[], address: string): string[] {
+    return [...new Set(contactsMatching(contacts, address).flatMap((contact) => signingKeyFingerprints(contact.keys, contact.previousKeys)))];
+}
+
+/** Page size and page cap for `fetchPinnedSigningFingerprints()` and `fetchSignerKeyState()` (500 is restapi's own
+ * `limit` cap). */
+export const PINNED_FINGERPRINT_PAGE_SIZE = 500;
+export const PINNED_FINGERPRINT_MAX_PAGES = 20;
+
+/** Every contact in `folderUids`, paged (`PINNED_FINGERPRINT_PAGE_SIZE`, at most `PINNED_FINGERPRINT_MAX_PAGES` pages
+ * per folder). A plain contacts read - never a Discovery lookup. */
+async function listContactsInFolders(folderUids: string[], client?: ApiClient): Promise<Contact[]> {
+    const contacts: Contact[] = [];
+    for (const folderUid of folderUids) {
+        for (let page = 0; page < PINNED_FINGERPRINT_MAX_PAGES; page++) {
+            const batch = await listContacts(folderUid, { limit: PINNED_FINGERPRINT_PAGE_SIZE, page }, client);
+            contacts.push(...batch);
+            if (batch.length < PINNED_FINGERPRINT_PAGE_SIZE) {
+                break;
+            }
+        }
+    }
+    return contacts;
+}
+
+/**
+ * Fetches the trusted signing-key fingerprints (pinned and previous - see `pinnedSigningFingerprintsFor()`) for a
+ * message sender's `address` from the contacts in `folderUids` (the reader's contacts folders), for
+ * `evaluateMessageSecurity()`'s `pinnedSignerFingerprints`. Reads only what is already stored on the reader's own
+ * contacts - never triggers a Discovery lookup, which must not happen on message receipt (it would leak read timing to
+ * the sender's server). Pages through each folder (`PINNED_FINGERPRINT_PAGE_SIZE`, at most
+ * `PINNED_FINGERPRINT_MAX_PAGES` pages per folder). A caller rendering many messages should cache the contact list and
+ * use `pinnedSigningFingerprintsFor()` instead.
+ */
+export async function fetchPinnedSigningFingerprints(folderUids: string[], address: string, client?: ApiClient): Promise<string[]> {
+    return pinnedSigningFingerprintsFor(await listContactsInFolders(folderUids, client), address);
+}
+
+/** A sender's stored signing-key state, for a key-changed comparison - see `signerKeyStateFor()`. */
+export interface SignerKeyState {
+    /** The currently pinned signing keys (every `useType: "sign"` key, revoked and expired ones included, so a UI can
+     * show their dates and status), de-duplicated by fingerprint. */
+    pinned: PublicKey[];
+    /** Previously pinned signing keys, newest `replacedAt` first, de-duplicated by fingerprint. */
+    previous: PreviousKey[];
+    /** The first unresolved signing-key conflict found, if any. */
+    conflict?: KeyConflict;
+}
+
+function uniqueByFingerprint<T extends PublicKey>(keys: T[]): T[] {
+    const seen = new Set<string>();
+    return keys.filter((key) => {
+        const fingerprint = key.fingerprint.toLowerCase();
+        if (seen.has(fingerprint)) {
+            return false;
+        }
+        seen.add(fingerprint);
+        return true;
+    });
+}
+
+/** The signing-key state of every contact in `contacts` with an email equal (case-insensitively) to `address`, merged -
+ * what a UI needs to compare a `signer_key_changed` message's certificate with the pinned and previous keys (their
+ * fingerprints and `notBefore`/`notAfter`/`revokedAt`/`replacedAt` dates) before calling `resolveKeyConflict()`. Empty
+ * `pinned`/`previous` and no `conflict` when no contact matches. */
+export function signerKeyStateFor(contacts: Contact[], address: string): SignerKeyState {
+    const matching = contactsMatching(contacts, address);
+    const pinned = uniqueByFingerprint(matching.flatMap((contact) => (contact.keys ?? []).filter((key) => key.useType === "sign")));
+    const previous = uniqueByFingerprint(
+        matching.flatMap((contact) => (contact.previousKeys ?? []).filter((key) => key.useType === "sign")).sort((a, b) => b.replacedAt - a.replacedAt),
+    );
+    const conflict = matching.flatMap((contact) => contact.keyConflicts ?? []).find((entry) => entry.useType === "sign");
+    return { pinned, previous, ...(conflict ? { conflict } : {}) };
+}
+
+/** Fetches `signerKeyStateFor()` for `address` from the contacts in `folderUids`, paging exactly like
+ * `fetchPinnedSigningFingerprints()`. Reads only stored contacts - never triggers a Discovery lookup. */
+export async function fetchSignerKeyState(folderUids: string[], address: string, client?: ApiClient): Promise<SignerKeyState> {
+    return signerKeyStateFor(await listContactsInFolders(folderUids, client), address);
+}
+
+/**
+ * Lists a folder's soft-deleted contacts
+ (for an Outlook-style "Deleted" view) — `deleted` is an ordinary
+ * queryable field on `Contact` (a `RecoverableBaseEntity`), so this is the same `find()` the plain listing
+ * above uses, just constrained to `deleted: true` instead of the framework's own default of excluding them.
+ *
+ * Read-only for now — deliberately no `restoreContact()`: `@rapidmx/restapi`'s generic
+ * `BaseScopedChildRoute.update()` looks the target record up via a plain `findOne()` with no
+ * `includeDeleted` option, so it 404s on an already-deleted record before ever reaching the point where
+ * setting `deleted: false` would matter. Restoring would need a real fix in `@rapidmx/restapi` itself
+ * (passing `includeDeleted: true` into that lookup) — out of scope for this pass; the "Deleted" view here
+ * is browse-only until that lands.
+ */
+export function listDeletedContacts(folderUid: string, params: ListParams = {}, client?: ApiClient): Promise<Contact[]> {
+    return withClient(
+        client,
+        `/mail/contacts?${buildQuery(params, { folderUid, deleted: "true", sort: JSON.stringify({ displayName: "ASC" }) })}`,
+    );
+}
+
+export function getContact(uid: string, client?: ApiClient): Promise<Contact> {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}`);
+}
+
+export interface ContactInput {
+    mailboxUid: string;
+    folderUid: string;
+    contactListUid?: string;
+    displayName: string;
+    givenName?: string;
+    surname?: string;
+    emails?: ContactEmail[];
+    phones?: ContactPhone[];
+    addresses?: ContactPostalAddress[];
+    company?: string;
+    jobTitle?: string;
+    notes?: string;
+    favorite?: boolean;
+    categories?: string[];
+}
+
+export function createContact(input: ContactInput, client?: ApiClient): Promise<Contact> {
+    return withClient(client, "/mail/contacts", {
+        method: "POST",
+        body: JSON.stringify({ emails: [], phones: [], addresses: [], ...input }),
+    });
+}
+
+export interface UpdateContactInput extends ContactInput {
+    uid: string;
+    version: number;
+}
+
+/** A minimal contact update: only `uid`/`version` are required, every other field is sent only if
+ * present. The server merges just the fields in the body and rejects server-managed ones
+ * (`dateCreated`/`dateModified`/etc.), so prefer sending only what actually changed over a whole
+ * fetched `Contact`. An `UpdateContactInput` is also a valid `ContactPatch`. */
+export type ContactPatch = Partial<Contact> & Pick<Contact, "uid" | "version">;
+
+export function updateContact(patch: ContactPatch, client?: ApiClient): Promise<Contact> {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(patch.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(patch),
+    });
+}
+
+/** Thin `updateContact()` wrapper for toggling favorite/star status — same pattern as `mailApi.ts`'s
+ * `setMessageRead()`/`tasksApi.ts`'s `setTaskCompleted()`. Sends only `uid`/`version`/`favorite`, never
+ * the rest of `contact` (the server rejects its managed fields). */
+export function setContactFavorite(contact: Contact, favorite: boolean, client?: ApiClient): Promise<Contact> {
+    return updateContact({ uid: contact.uid, version: contact.version, favorite }, client);
+}
+
+export function deleteContact(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+
+export interface ContactList {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+}
+
+/** Lists a mailbox's contact lists (Outlook-style "Your contact lists"), alphabetically by name. */
+export function listContactLists(mailboxUid: string, params: ListParams = {}, client?: ApiClient): Promise<ContactList[]> {
+    return withClient(client, `/mail/contact-lists?${buildQuery(params, { mailboxUid, sort: JSON.stringify({ name: "ASC" }) })}`);
+}
+
+export function createContactList(input: { mailboxUid: string; name: string }, client?: ApiClient): Promise<ContactList> {
+    return withClient(client, "/mail/contact-lists", { method: "POST", body: JSON.stringify(input) });
+}
+
+export function updateContactList(
+    input: { uid: string; version: number; name: string },
+    client?: ApiClient,
+): Promise<ContactList> {
+    return withClient(client, `/mail/contact-lists/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteContactList(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/contact-lists/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/lib/contacts/vcard.ts

@@ -0,0 +1,197 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Pure client-side vCard 3.0 generate/parse — `@rapidmx/restapi` has no vCard import/export support of its
+ * own, and Outlook's Contacts UI treats this as a purely local file-format concern (a `.vcf` file never
+ * touches the server as anything but ordinary `Contact` field values), so there's nothing to add there.
+ */
+import type { Contact, ContactAddressKind, ContactInput } from "./contactsApi.js";
+
+/** Escapes a text value (RFC 6350 §3.4): backslash, comma and semicolon are backslash-escaped, and every
+ * line break - CRLF, bare CR or bare LF - becomes `\n`, so a value can never break the content line. */
+function escapeVCardValue(value: string): string {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/,/g, "\\,")
+        .replace(/;/g, "\\;")
+        .replace(/\r\n|\r|\n/g, "\\n");
+}
+
+/** Unescapes a text value in a single pass, so an escaped backslash followed by `n` (`\\n`) stays a
+ * literal backslash + `n` instead of becoming a newline. `\n`/`\N` is a newline; any other escaped
+ * character is itself. */
+function unescapeVCardValue(value: string): string {
+    return value.replace(/\\([\s\S])/g, (_match, ch: string) => (ch === "n" || ch === "N" ? "\n" : ch));
+}
+
+/** Splits a structured value (`N`, `ADR`) on its unescaped `;` separators, then unescapes each component. */
+function splitStructuredValue(value: string): string[] {
+    const components: string[] = [];
+    let current = "";
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === "\\" && i + 1 < value.length) {
+            current += ch + value[++i];
+        } else if (ch === ";") {
+            components.push(unescapeVCardValue(current));
+            current = "";
+        } else {
+            current += ch;
+        }
+    }
+    components.push(unescapeVCardValue(current));
+    return components;
+}
+
+/** Builds a single vCard 3.0 record for one contact. */
+export function contactToVCard(contact: Contact): string {
+    const lines: string[] = ["BEGIN:VCARD", "VERSION:3.0"];
+    lines.push(`N:${escapeVCardValue(contact.surname ?? "")};${escapeVCardValue(contact.givenName ?? "")};;;`);
+    lines.push(`FN:${escapeVCardValue(contact.displayName)}`);
+    if (contact.company) {
+        lines.push(`ORG:${escapeVCardValue(contact.company)}`);
+    }
+    if (contact.jobTitle) {
+        lines.push(`TITLE:${escapeVCardValue(contact.jobTitle)}`);
+    }
+    for (const email of contact.emails) {
+        lines.push(`EMAIL;TYPE=${email.type.toUpperCase()}:${escapeVCardValue(email.address)}`);
+    }
+    for (const phone of contact.phones) {
+        lines.push(`TEL;TYPE=${phone.type.toUpperCase()}:${escapeVCardValue(phone.phoneNumber)}`);
+    }
+    for (const address of contact.addresses) {
+        const parts = [
+            "",
+            "",
+            address.street ?? "",
+            address.city ?? "",
+            address.state ?? "",
+            address.postalCode ?? "",
+            address.country ?? "",
+        ];
+        lines.push(`ADR;TYPE=${address.type.toUpperCase()}:${parts.map(escapeVCardValue).join(";")}`);
+    }
+    if (contact.notes) {
+        lines.push(`NOTE:${escapeVCardValue(contact.notes)}`);
+    }
+    lines.push("END:VCARD");
+    return lines.join("\r\n");
+}
+
+/** Builds a single `.vcf` file's text content from multiple contacts (one `BEGIN:VCARD`/`END:VCARD` block
+ * per contact — the standard way multiple vCards share one file). */
+export function contactsToVCardFile(contacts: Contact[]): string {
+    return contacts.map(contactToVCard).join("\r\n");
+}
+
+/** A parsed vCard's fields, shaped as a partial `ContactInput` missing only the `mailboxUid`/`folderUid`
+ * scope (the caller supplies those, since they're not part of the vCard format itself). */
+export type ParsedVCardContact = Omit<ContactInput, "mailboxUid" | "folderUid">;
+
+/** Index of the content line's name/value separator: the first `:` outside a quoted parameter value. */
+function valueSeparatorIndex(line: string): number {
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        if (line[i] === '"') {
+            inQuotes = !inQuotes;
+        } else if (line[i] === ":" && !inQuotes) {
+            return i;
+        }
+    }
+    return -1;
+}
+
+/**
+ * Maps a property's type parameters onto `ContactAddressKind`: every `TYPE=` value (vCard 3/4, including
+ * comma lists and quoted lists like `TYPE="work,voice"`) plus vCard 2.1's bare parameters (`EMAIL;WORK:`)
+ * are collected case-insensitively; `work` wins, then `home`, and anything else (`internet`, `cell`,
+ * `pref`, no type at all) is `other`.
+ */
+function normalizeType(params: string[]): ContactAddressKind {
+    const tokens = new Set<string>();
+    for (const param of params) {
+        const eq = param.indexOf("=");
+        const name = eq === -1 ? "TYPE" : param.slice(0, eq).trim().toUpperCase();
+        if (name !== "TYPE") {
+            continue;
+        }
+        for (const token of param.slice(eq + 1).replace(/"/g, "").split(",")) {
+            tokens.add(token.trim().toLowerCase());
+        }
+    }
+    return tokens.has("work") ? "work" : tokens.has("home") ? "home" : "other";
+}
+
+/**
+ * Parses one or more vCard 2.1/3.0/4.0 records from a `.vcf` file's text content. Deliberately tolerant of
+ * fields this app doesn't model (PHOTO, BDAY, etc. — silently ignored) and of the `TYPE=` parameter being
+ * absent (defaults to "other") — real-world exported vCards vary a lot in exactly which optional parameters
+ * they include. Folded lines (a line break followed by a space or tab) are unfolded first; property group
+ * prefixes (`item1.EMAIL`, as Apple Contacts writes) are ignored; `TYPE` values are normalized (see
+ * `normalizeType()`); structured values are split on unescaped `;` only.
+ */
+export function parseVCards(text: string): ParsedVCardContact[] {
+    // Unfold first, then split only on a line that is exactly BEGIN:VCARD - a NOTE (or a folded line) that
+    // merely contains the text "BEGIN:VCARD" must not start a bogus record.
+    const unfolded = text.replace(/(?:\r\n|\r|\n)[ \t]/g, "");
+    const cards = unfolded.split(/^[ \t]*BEGIN:VCARD[ \t]*$/im).slice(1);
+    return cards.map((card) => {
+        const contact: ParsedVCardContact = { displayName: "", emails: [], phones: [], addresses: [] };
+        const lines = card.split(/\r\n|\r|\n/);
+        for (const rawLine of lines) {
+            const line = rawLine.trim();
+            const colonIndex = valueSeparatorIndex(line);
+            if (colonIndex === -1) {
+                continue;
+            }
+            const key = line.slice(0, colonIndex);
+            const rawValue = line.slice(colonIndex + 1);
+            const value = unescapeVCardValue(rawValue);
+            const [groupedName, ...params] = key.split(";");
+            const name = groupedName.slice(groupedName.lastIndexOf(".") + 1).toUpperCase();
+            const type = normalizeType(params);
+
+            switch (name) {
+                case "FN":
+                    contact.displayName = value;
+                    break;
+                case "N": {
+                    const [surname, given] = splitStructuredValue(rawValue);
+                    if (surname) contact.surname = surname;
+                    if (given) contact.givenName = given;
+                    break;
+                }
+                case "ORG":
+                    // ORG is structured too (organization;unit;...) - only the organization name is modeled.
+                    contact.company = splitStructuredValue(rawValue)[0];
+                    break;
+                case "TITLE":
+                    contact.jobTitle = value;
+                    break;
+                case "EMAIL":
+                    contact.emails!.push({ address: value, type });
+                    break;
+                case "TEL":
+                    contact.phones!.push({ phoneNumber: value, type });
+                    break;
+                case "ADR": {
+                    const [, , street, city, state, postalCode, country] = splitStructuredValue(rawValue);
+                    contact.addresses!.push({ street, city, state, postalCode, country, type });
+                    break;
+                }
+                case "NOTE":
+                    contact.notes = value;
+                    break;
+                default:
+                    break;
+            }
+        }
+        if (!contact.displayName) {
+            contact.displayName = [contact.givenName, contact.surname].filter(Boolean).join(" ") || "Unnamed contact";
+        }
+        return contact;
+    });
+}

package/lib/crypto/composeSecurity.ts

@@ -0,0 +1,140 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Compose-time decision logic for `specs/end-to-end_encryption.md`'s Digital Signatures and Encryption
+ * sections — kept as pure, side-effect-free functions (no `fetch`, no crypto) precisely so the actual
+ * discovery round trip (`keyvaultApi.ts`'s `lookupKeys()`) and MIME assembly (`smimeMessage.ts`) stay in
+ * the caller (`ComposeWindow.tsx`), which owns the async orchestration and error handling; this module
+ * only decides *what* a compose window should do once it has the facts.
+ *
+ * **Recipient tier classification is a client-side approximation.** The spec's three tiers
+ * (`specs/end-to-end_encryption.md`'s "Terminology": same-organisation / federated peer / external) are
+ * a server-side administrative concept - "the specific RapidMX server and the domains it controls" - that
+ * `@rapidmx/restapi` 0.6.0 does not actually expose to the client (`KeyLookupResult`/`KeyringUpdate`
+ * carry no tier field; confirmed by reading `util/KeyringUtils.ts`). `classifyRecipientTier()` below
+ * approximates it as "same domain as the sender's own address" vs. "a domain discovery found keys for"
+ * vs. "everything else" - the same domain-suffix heuristic used elsewhere for this class of judgment,
+ * not a guarantee. A real fix would be a restapi endpoint exposing which domains a server actually
+ * controls; until then this is a disclosed approximation, not a silent one.
+ */
+import { findActivePublicKey, type EncryptionPolicy, type KeyLookupResult, type PolicyState, type PublicKey } from "./keyvaultApi.js";
+
+export type RecipientTier = "sameOrg" | "federated" | "external";
+
+/** See this module's own doc comment for why this is an approximation, not an authoritative classification. */
+export function classifyRecipientTier(ownAddress: string, recipientAddress: string, hasDiscoveredKeys: boolean): RecipientTier {
+    const ownDomain = ownAddress.split("@")[1]?.toLowerCase();
+    const recipientDomain = recipientAddress.split("@")[1]?.toLowerCase();
+    if (ownDomain && recipientDomain && ownDomain === recipientDomain) {
+        return "sameOrg";
+    }
+    return hasDiscoveredKeys ? "federated" : "external";
+}
+
+function policyStateForTier(policy: EncryptionPolicy, tier: RecipientTier): PolicyState {
+    switch (tier) {
+        case "sameOrg":
+            return policy.encryptSameOrg;
+        case "federated":
+            return policy.encryptFederated;
+        case "external":
+            return policy.encryptExternal;
+    }
+}
+
+export interface RecipientEncryptionStatus {
+    address: string;
+    tier: RecipientTier;
+    /** The recipient's currently-active encryption certificate, if they have published (and this device
+     * has discovered) one. */
+    encryptCert?: PublicKey;
+    /** Whether this recipient *can* be encrypted to at all right now - false when there's no usable key,
+     * or the tier's policy is `prohibited`. */
+    canEncrypt: boolean;
+    /** Whether encryption should default ON for this recipient specifically: per spec, "MUST default to
+     * on only when both parties advertise mutual" AND the tier's policy is `automatic`. */
+    autoEncrypt: boolean;
+    /** Set (non-undefined) exactly when policy blocks encryption outright for this recipient's tier - the
+     * spec: "the client MUST explain why encryption is unavailable rather than silently omitting the
+     * control." `undefined` in every other case, including "no key found," which is not a policy block. */
+    prohibitedReason?: string;
+}
+
+/** Per-recipient encryption eligibility, given this device's own encryption preference and the
+ * system-wide policy. One entry per (address, lookup result) pair the caller already resolved via
+ * `lookupKeys()` - this function does no discovery itself. */
+export function resolveRecipientEncryption(
+    ownAddress: string,
+    ownPrefersMutual: boolean,
+    policy: EncryptionPolicy,
+    recipientAddress: string,
+    lookup: KeyLookupResult | undefined,
+): RecipientEncryptionStatus {
+    const encryptCert = lookup ? findActivePublicKey(lookup.keys, "encrypt") : undefined;
+    const tier = classifyRecipientTier(ownAddress, recipientAddress, !!lookup && lookup.keys.length > 0);
+    const policyState = policyStateForTier(policy, tier);
+
+    if (policyState === "prohibited") {
+        return {
+            address: recipientAddress,
+            tier,
+            encryptCert,
+            canEncrypt: false,
+            autoEncrypt: false,
+            prohibitedReason: "Your organization's encryption policy does not allow encrypting messages to this recipient.",
+        };
+    }
+
+    if (!encryptCert) {
+        return { address: recipientAddress, tier, canEncrypt: false, autoEncrypt: false };
+    }
+
+    const recipientPrefersMutual = lookup?.encryptPreference?.preferEncrypt === "mutual";
+    const mutual = ownPrefersMutual && recipientPrefersMutual;
+    return {
+        address: recipientAddress,
+        tier,
+        encryptCert,
+        canEncrypt: true,
+        autoEncrypt: policyState === "automatic" && mutual,
+    };
+}
+
+export interface MessageEncryptionDecision {
+    /** Whether the compose window's encryption toggle should default to checked - true only when every
+     * recipient independently defaults to encrypted. Seeds the toggle's *initial* state only; the user
+     * can still turn it on manually even when this is false, subject to `canEncryptAll`. */
+    autoEncrypt: boolean;
+    /** Every recipient the message *could* be encrypted to right now. */
+    canEncryptAll: boolean;
+    /** Recipients that cannot currently be encrypted to (no key, or policy-prohibited) - the spec's
+     * "Multiple Recipients" all-or-nothing case: when this is non-empty and the user still wants
+     * encryption, the client MUST offer to send in plaintext or remove these recipients, never split. */
+    blockedRecipients: RecipientEncryptionStatus[];
+}
+
+/** Combines every recipient's individual status into the one decision a compose window's UI actually
+ * needs: whether to default the toggle on, and whether an all-or-nothing prompt is required. */
+export function decideMessageEncryption(recipients: RecipientEncryptionStatus[]): MessageEncryptionDecision {
+    if (recipients.length === 0) {
+        return { autoEncrypt: false, canEncryptAll: false, blockedRecipients: [] };
+    }
+    const blockedRecipients = recipients.filter((r) => !r.canEncrypt);
+    return {
+        autoEncrypt: recipients.every((r) => r.autoEncrypt),
+        canEncryptAll: blockedRecipients.length === 0,
+        blockedRecipients,
+    };
+}
+
+/** Detects list traffic per the spec's "Mailing lists" note under Digital Signatures: a footer a list
+ * appends after signing invalidates the signature, so the client MAY suppress signing for it. `headers`
+ * is whatever the caller already has on hand (e.g. a `Contact`'s known list-membership flag) - this
+ * module has no way to inspect list membership itself, so it just applies the rule to inputs the caller
+ * supplies. Currently unused by any caller (no UI surfaces distribution-list membership to compose yet -
+ * a disclosed gap, not a silent one; see this module's own file-level doc comment). */
+export function isLikelyMailingList(headers: { listId?: string; listUnsubscribe?: string }): boolean {
+    return !!(headers.listId || headers.listUnsubscribe);
+}

package/lib/crypto/encoding.ts

@@ -0,0 +1,36 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Plain base64/base64url <-> `Uint8Array` conversions shared by every `crypto/*` module. Deliberately
+ * `Buffer`-free — this code runs in a browser tab and an Electron renderer alike, and `Buffer` is not
+ * guaranteed to exist in either without a bundler polyfill.
+ */
+
+export function toBase64(bytes: Uint8Array): string {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+
+export function fromBase64(base64: string): Uint8Array {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+
+export function toBase64Url(bytes: Uint8Array): string {
+    return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function fromBase64Url(base64url: string): Uint8Array {
+    const padded = base64url.replace(/-/g, "+").replace(/_/g, "/");
+    const padding = padded.length % 4 === 0 ? "" : "=".repeat(4 - (padded.length % 4));
+    return fromBase64(padded + padding);
+}