@rapidmx/web-client 0.20.0 → 0.22.0

package/lib/mail/mailDetailHooks.ts

@@ -0,0 +1,57 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { Attachment, Message, listAttachments, setMessageRead } from "./mailApi.js";
+
+/** Loads a message's attachments (only when it actually has any) — shared by every place a message is read. */
+export function useMessageAttachments(message: Message | null): Attachment[] {
+    const [attachments, setAttachments] = useState<Attachment[]>([]);
+
+    useEffect(() => {
+        if (!message || !message.hasAttachments) {
+            setAttachments([]);
+            return;
+        }
+        listAttachments(message.folderUid, message.uid)
+            .then(setAttachments)
+            .catch(() => setAttachments([]));
+        // Only the fields the fetch actually depends on — not the whole `message` object, which gets a new
+        // reference on every metadata-only patch (e.g. `useMarkMessageRead`'s `onUpdated(updated)`, or a
+        // star/flag/label change wired to the same state) and would otherwise trigger a needless re-fetch.
+        // `folderUid` IS included: `moveMessage()`/`archiveMessage()` change it while preserving uid/hasAttachments
+        // (the same "new object reference, same uid" shape as a metadata-only patch), and dropping it would leave
+        // a stale fetch pointed at the message's old folder after a move — folder changes are rare enough that
+        // including it doesn't reintroduce the over-fetching this dependency array was narrowed to avoid.
+    }, [message?.uid, message?.hasAttachments, message?.folderUid]);
+
+    return attachments;
+}
+
+/**
+ * Marks a message read the first time it's viewed. `onUpdated` receives the server's updated copy — the
+ * desktop reading pane patches its in-memory message list with it; the mobile detail route (which has no
+ * list to patch) just replaces its own local `message` state. Best-effort: a failed update shouldn't block
+ * reading the message, matching this app's existing `handleSelect` behavior.
+ */
+export function useMarkMessageRead(message: Message | null, onUpdated: (updated: Message) => void): void {
+    useEffect(() => {
+        if (!message || message.flags.read) {
+            return;
+        }
+        let cancelled = false;
+        setMessageRead(message, true)
+            .then((updated) => {
+                if (!cancelled) {
+                    onUpdated(updated);
+                }
+            })
+            .catch(() => {
+                // Best-effort — see doc comment above.
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, [message]);
+}

package/lib/mail/mailFilterRulesApi.ts

@@ -0,0 +1,116 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `MailFilterRule` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped (unlike `TransportRule`, which is trusted-role-only
+ * and org-wide): every list/create call must carry `mailboxUid`, checked against that mailbox's own
+ * ACL, same pattern as `Message`/`Task`/`Note`/`Contact`. Evaluated by `ScanQueueJob` immediately after
+ * a message is verdicted "deliver" and before it's filed into the mailbox's Inbox — a live, enforced
+ * feature, not a data-model-only stub.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { MessageImportance } from "./mailApi.js";
+
+export type { ListParams };
+
+export type MailFilterActionType = "move_to_folder" | "copy_to_folder" | "delete" | "mark_as_read" | "forward" | "apply_label";
+
+export interface MailFilterAction {
+    type: MailFilterActionType;
+    /** Required for `move_to_folder`/`copy_to_folder`. */
+    folderUid?: string;
+    /** Required for `forward`. */
+    forwardTo?: string;
+    /** The `Label.uid` to apply (`labelsApi.ts`). Required for `apply_label`. */
+    labelUid?: string;
+}
+
+export interface MailFilterConditions {
+    /** Substrings of the From header, case-insensitive: `ann@x.com` also matches `joann@x.com`. Use `fromEquals` to name one sender exactly. */
+    fromContains?: string[];
+    /** Plain addresses, matched exactly and case-insensitively against the From header's address OR the envelope sender (`ann@x.com` does not match `joann@x.com`).
+     * At most 100. A server before this condition ignores it, so the rule would match every message. */
+    fromEquals?: string[];
+    /** Domains (`x.com`, no `@`), matched exactly against the domain of the From header's address or of the envelope sender (`x.com` is not `mail.x.com`). At most 100. */
+    fromDomainEquals?: string[];
+    subjectContains?: string[];
+    bodyContains?: string[];
+    toCcContains?: string[];
+    hasAttachment?: boolean;
+    importance?: MessageImportance;
+}
+
+export interface MailFilterRule {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+    enabled: boolean;
+    sequence: number;
+    stopProcessingRules: boolean;
+    conditions: MailFilterConditions;
+    actions: MailFilterAction[];
+}
+
+/** `client`, given by every function below, 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), every function here behaves exactly as before. */
+export function listMailFilterRules(mailboxUid: string, params: ListParams = {}, client?: ApiClient): Promise<MailFilterRule[]> {
+    return withClient(client, `/mail/mail-filter-rules?${buildQuery(params, { mailboxUid })}`);
+}
+
+export function getMailFilterRule(uid: string, client?: ApiClient): Promise<MailFilterRule> {
+    return withClient(client, `/mail/mail-filter-rules/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateMailFilterRuleInput {
+    mailboxUid: string;
+    name: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: MailFilterConditions;
+    actions?: MailFilterAction[];
+}
+
+export function createMailFilterRule(input: CreateMailFilterRuleInput, client?: ApiClient): Promise<MailFilterRule> {
+    return withClient(client, "/mail/mail-filter-rules", {
+        method: "POST",
+        body: JSON.stringify({
+            enabled: true,
+            sequence: 0,
+            stopProcessingRules: false,
+            conditions: {},
+            actions: [],
+            ...input,
+        }),
+    });
+}
+
+export interface UpdateMailFilterRuleInput {
+    uid: string;
+    version: number;
+    name?: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: MailFilterConditions;
+    actions?: MailFilterAction[];
+}
+
+export function updateMailFilterRule(input: UpdateMailFilterRuleInput, client?: ApiClient): Promise<MailFilterRule> {
+    return withClient(client, `/mail/mail-filter-rules/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteMailFilterRule(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/mail-filter-rules/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/lib/mail/mailSignaturesApi.ts

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `MailSignature` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped, same pattern as `mailFilterRulesApi.ts`. Composition
+ * is entirely this app's own job: restapi never assembles a signature into a message body itself (see
+ * its own `resolveDefaultSignature()` doc comment) — `ComposeWindow.tsx` is what actually inserts a
+ * resolved signature's `contentHtml` into a new draft.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+export interface MailSignature {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+    contentHtml: string;
+    /** At most one signature per mailbox should have this `true` — enforced by convention (the caller
+     * toggles any previous default off itself), not by a database constraint. Applied to a fresh,
+     * non-reply/forward compose. */
+    isDefaultForNewMessages: boolean;
+    /** Same single-default convention as `isDefaultForNewMessages`, applied to replies/forwards
+     * instead — mirrors Outlook Web Access's separate "Replies/forwards" signature selector. */
+    isDefaultForReplyForward: boolean;
+}
+
+/** `client`, given by every function below, 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), every function here behaves exactly as before. */
+export function listMailSignatures(mailboxUid: string, params: ListParams = {}, client?: ApiClient): Promise<MailSignature[]> {
+    return withClient(client, `/mail/mail-signatures?${buildQuery(params, { mailboxUid })}`);
+}
+
+export function getMailSignature(uid: string, client?: ApiClient): Promise<MailSignature> {
+    return withClient(client, `/mail/mail-signatures/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateMailSignatureInput {
+    mailboxUid: string;
+    name: string;
+    contentHtml?: string;
+    isDefaultForNewMessages?: boolean;
+    isDefaultForReplyForward?: boolean;
+}
+
+export function createMailSignature(input: CreateMailSignatureInput, client?: ApiClient): Promise<MailSignature> {
+    return withClient(client, "/mail/mail-signatures", {
+        method: "POST",
+        body: JSON.stringify({
+            contentHtml: "",
+            isDefaultForNewMessages: false,
+            isDefaultForReplyForward: false,
+            ...input,
+        }),
+    });
+}
+
+export interface UpdateMailSignatureInput {
+    uid: string;
+    version: number;
+    name?: string;
+    contentHtml?: string;
+    isDefaultForNewMessages?: boolean;
+    isDefaultForReplyForward?: boolean;
+}
+
+export function updateMailSignature(input: UpdateMailSignatureInput, client?: ApiClient): Promise<MailSignature> {
+    return withClient(client, `/mail/mail-signatures/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteMailSignature(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/mail-signatures/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/lib/mail/mailboxAccessApi.ts

@@ -0,0 +1,106 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseMailboxAccessRoute` (`GET/PUT/DELETE /mail/mailboxes/:id/
+ * access[/:userOrRoleId]`, `GET /mail/mailboxes/lookup-by-email`) - a friendlier, purpose-built layer over
+ * mailbox delegate access than this package's own `getMailboxAcl()`/`grantMailboxAccess()`/
+ * `revokeMailboxAccess()` (`mailApi.ts`), which stay as-is for their one existing caller (the admin-only
+ * `ShareAccessCard`). Those wrap the fully generic `BaseACLRoute` directly (raw `ACLRecord.actions[]`,
+ * requires the caller hold literal `ACLAction.FULL`); this module's routes are gated at plain `"update"`
+ * and speak a simple 2-tier `"viewer"`/`"manager"` vocabulary instead, so a non-admin mailbox owner or
+ * delegate can use them too.
+ */
+import { ApiClient, withClient } from "../util/api.js";
+
+/** A role that can be granted. */
+export type MailboxAccessRole = "viewer" | "manager";
+
+/** A member's role as listed: `"custom"` for any other set of actions granted outside this API, which can't be set
+ * here - see `actions` for what it allows. */
+export type MailboxAccessMemberRole = MailboxAccessRole | "custom";
+
+export interface MailboxAccessMember {
+    userOrRoleId: string;
+    role: MailboxAccessMemberRole;
+    /** The ACL actions the member holds. */
+    actions?: string[];
+    /** `userOrRoleId` is not a user uid (a username or address typed in free text, say): a person's token carries a uid, never
+     * that string, so the entry almost certainly grants nothing to anyone. Replace it with the user it was meant for. */
+    noEffect?: boolean;
+}
+
+/** The person a typed principal - a mailbox address, an auth-server username or e-mail alias, or a user uid - resolved to. */
+export interface ResolvedPrincipal {
+    /** The user uid every grant is stored against. */
+    userUid: string;
+    /** Known when the person owns a mailbox on this server. */
+    displayName?: string;
+    address?: string;
+}
+
+/** `client`, given by every function below, 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), every function here behaves exactly as before. */
+
+/** Who a typed principal is, without granting anything - rejects with a 404 `ApiRequestError` ("No user found for ...") for nobody. */
+export function resolveMailboxPrincipal(mailboxUid: string, principal: string, client?: ApiClient): Promise<ResolvedPrincipal> {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/resolve?principal=${encodeURIComponent(principal)}`);
+}
+
+export interface MailboxOwnerLookup {
+    userUid: string;
+    displayName: string;
+}
+
+/** Lists a mailbox's delegate members (excludes the owner's own implicit grant) - rejects with a 403
+ * `ApiRequestError` if the caller doesn't hold at least `"update"` on the mailbox (an administrator, trusted + elevated, may
+ * list any mailbox's members through the audited administration path). */
+export function listMailboxAccess(mailboxUid: string, client?: ApiClient): Promise<MailboxAccessMember[]> {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access`);
+}
+
+/** Grants (or, if already a member, updates the role of) a delegate's access to a mailbox. `userOrRoleId` names the PERSON - a user
+ * uid, or anything the server resolves to one (a mailbox address, an auth-server username or e-mail alias): only the resolved uid is
+ * stored, and a name that resolves to nobody rejects with a 400 `ApiRequestError` ("No user found for ..."). */
+export function setMailboxAccess(mailboxUid: string, userOrRoleId: string, role: MailboxAccessRole, client?: ApiClient): Promise<MailboxAccessMember> {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/${encodeURIComponent(userOrRoleId)}`, {
+        method: "PUT",
+        body: JSON.stringify({ role }),
+    });
+}
+
+/** What the signed-in caller may do in a mailbox, as the server's ACLs evaluate it: their own and delegate access - a
+ * trusted role adds nothing, so an administrator with no grant on a mailbox gets `false` throughout. */
+export interface MyMailboxAccess {
+    canRead: boolean;
+    /** Create items in the mailbox: drafts, events, contacts, to-dos. */
+    canCreate: boolean;
+    canUpdate: boolean;
+    canDelete: boolean;
+    /** Manage who else has access. */
+    canManage: boolean;
+}
+
+/** The signed-in caller's own access to a mailbox. */
+export function getMyMailboxAccess(mailboxUid: string, client?: ApiClient): Promise<MyMailboxAccess> {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/me`);
+}
+
+/** Revokes a delegate's access to a mailbox - never rejects for a `userOrRoleId` that wasn't a member. */
+export function removeMailboxAccess(mailboxUid: string, userOrRoleId: string, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/access/${encodeURIComponent(userOrRoleId)}`, { method: "DELETE" });
+}
+
+/**
+ * Resolves an email address to the person who owns the mailbox at that address, for a "share this
+ * mailbox with someone" UI to grant access by uid after the caller types an email - there is no separate
+ * user/identity directory anywhere in this platform (see `BaseMailboxAccessRoute`'s own doc comment), so
+ * this only ever matches an existing `Mailbox`'s own address. Resolves to `null` (not a thrown error) for
+ * an address with no matching mailbox, or one that only matches a shared (ownerless) mailbox - both are
+ * "no person found," a normal, expected outcome, not a failure.
+ */
+export function lookupMailboxOwnerByEmail(email: string, client?: ApiClient): Promise<MailboxOwnerLookup | null> {
+    return withClient(client, `/mail/mailboxes/lookup-by-email?email=${encodeURIComponent(email)}`);
+}

package/lib/mail/mailboxImportApi.ts

@@ -0,0 +1,87 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR data-portability import (`BaseMailboxImportRoute`,
+ * mounted at `mail/mailbox-import-requests`) — the counterpart to `dataExportApi.ts`. Import runs
+ * asynchronously (restapi's own `MailboxImportJob`, not this client) — `uploadMailboxImport()` only
+ * stages the upload and returns the `pending` request; poll `getImportRequest()`/`listImportRequests()`
+ * for `status` to become `"completed"` (with `importedCount`/`failedCount`) or `"failed"`.
+ */
+import { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+import { RequestListParams, buildRequestListQuery } from "../util/apiQuery.js";
+
+export type { RequestListParams };
+
+export type MailboxImportFormat = "mbox" | "pst";
+export type MailboxImportStatus = "pending" | "processing" | "completed" | "failed";
+
+export interface MailboxImportRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    targetFolderUid: string;
+    format: MailboxImportFormat;
+    sourceBlobKey: string;
+    status: MailboxImportStatus;
+    importedCount?: number;
+    failedCount?: number;
+    errorMessage?: string;
+    /** How many times the server job has claimed this request into `"processing"` (a stalled claim is reclaimed
+     * back to `"pending"` until the job's max attempts, then marked `"failed"`). */
+    processingAttempts?: number;
+}
+
+export interface UploadMailboxImportInput {
+    format: MailboxImportFormat;
+    targetFolderUid: string;
+    /** Only honored when the caller is a trusted admin — an ordinary caller's own mailbox is always
+     * used, regardless of what (if anything) is supplied here. */
+    mailboxUid?: string;
+}
+
+/**
+ * Uploads `file`'s raw bytes as a new mailbox-import request. Bypasses `apiFetch` — that helper always
+ * forces `Content-Type: application/json`, which would corrupt binary content; this sends the file's own
+ * bytes directly instead, matching `BaseMailboxImportRoute.create()`'s expectation of a raw request body
+ * with `format`/`targetFolderUid`/`mailboxUid` as query-string parameters, not a JSON body — the same
+ * shape `mailApi.ts`'s `uploadAttachment()` already establishes for a raw-bytes upload.
+ */
+export async function uploadMailboxImport(file: File, input: UploadMailboxImportInput): Promise<MailboxImportRequest> {
+    const params = new URLSearchParams({ format: input.format, targetFolderUid: input.targetFolderUid });
+    if (input.mailboxUid) {
+        params.set("mailboxUid", input.mailboxUid);
+    }
+    const res = await fetch(apiUrl(`/mail/mailbox-import-requests?${params.toString()}`), {
+        method: "POST",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": input.format === "pst" ? "application/vnd.ms-outlook" : "application/mbox" }),
+        body: file,
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    const responseBody = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+    if (!res.ok) {
+        const message = (responseBody && (responseBody.message || responseBody.error)) || res.statusText || "Upload failed.";
+        throw new ApiRequestError(message, res.status, responseBody?.code);
+    }
+    return responseBody as MailboxImportRequest;
+}
+
+/** `client`, given by every function below that isn't a raw-bytes upload, 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), every
+ * function here behaves exactly as before. */
+
+/** A trusted caller sees every request; anyone else sees only their own (`requestedByUserUid`). Newest
+ * first; `params` pages through them (`limit` capped at 500 server-side). */
+export function listImportRequests(params: RequestListParams = {}, client?: ApiClient): Promise<MailboxImportRequest[]> {
+    return withClient(client, `/mail/mailbox-import-requests${buildRequestListQuery(params)}`);
+}
+
+export function getImportRequest(uid: string, client?: ApiClient): Promise<MailboxImportRequest> {
+    return withClient(client, `/mail/mailbox-import-requests/${encodeURIComponent(uid)}`);
+}

package/lib/mail/messageBodySanitizer.ts

@@ -0,0 +1,129 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Client-side sanitizing for message bodies the server never sanitized (decrypted or verified content) and for
+ * message HTML re-embedded elsewhere (a reply's quote). DOMPurify's defaults drop scripts, `on*` handlers and
+ * `javascript:` URLs; on top of that every remote resource reference is removed, so rendering or quoting a body
+ * can't ping a tracker. Only `data:` and `cid:` references survive.
+ */
+import DOMPurify from "dompurify";
+
+const EMBEDDED_URI = /^\s*(?:data|cid):/i;
+/** Attributes whose value makes the browser fetch a resource (as opposed to a user-clicked link). */
+const RESOURCE_URI_ATTRIBUTES = new Set(["src", "srcset", "background", "poster", "lowsrc", "dynsrc", "xlink:href", "action", "formaction"]);
+
+/** Decodes CSS escapes first (so an escaped `u\72l(` can't hide from the checks below), then drops every
+ * `@import` and neutralizes every `url()`/`image-set()` reference that isn't a `data:`/`cid:` URI. */
+export function stripRemoteCssUrls(css: string): string {
+    return css
+        .replace(/\\([0-9a-f]{1,6})\s?/gi, (_match, hex: string) => String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff)))
+        .replace(/\\(.)/g, "$1")
+        .replace(/@import[^;]*;?/gi, "")
+        .replace(/(?:-webkit-)?image-set\((?:[^()]|\([^()]*\))*\)/gi, (match) =>
+            [...match.matchAll(/(["'])(.*?)\1/g)].every(([, , uri]) => EMBEDDED_URI.test(uri)) ? match : "none",
+        )
+        .replace(/url\(\s*(["']?)(.*?)\1\s*\)/gi, (match, _quote: string, uri: string) => (EMBEDDED_URI.test(uri) ? match : "none"));
+}
+
+type Purifier = ReturnType<typeof DOMPurify>;
+let bodyPurifier: Purifier | undefined;
+
+/** A dedicated DOMPurify instance (hooks registered here never leak into any other DOMPurify caller) that
+ * additionally strips every remote resource reference - see `stripRemoteCssUrls()`. `undefined` without a DOM
+ * (server-side rendering), where DOMPurify can't sanitize at all. */
+function getBodyPurifier(): Purifier | undefined {
+    if (bodyPurifier) {
+        return bodyPurifier;
+    }
+    if (typeof window === "undefined") {
+        return undefined;
+    }
+    const purifier = DOMPurify(window);
+    if (!purifier.isSupported) {
+        return undefined;
+    }
+    purifier.addHook("uponSanitizeElement", (node, data) => {
+        if (data.tagName === "style") {
+            // An element's `textContent` is always a string (only documents/doctypes yield null).
+            node.textContent = stripRemoteCssUrls(node.textContent as string);
+        }
+    });
+    purifier.addHook("uponSanitizeAttribute", (node, data) => {
+        const name = data.attrName.toLowerCase();
+        if (name === "style") {
+            data.attrValue = stripRemoteCssUrls(data.attrValue);
+            return;
+        }
+        const isNavigationLink = name === "href" && ["a", "area"].includes(node.nodeName.toLowerCase());
+        if (RESOURCE_URI_ATTRIBUTES.has(name) || (name === "href" && !isNavigationLink)) {
+            const candidates = name === "srcset" ? data.attrValue.split(/,\s+/) : [data.attrValue];
+            if (!candidates.every((candidate) => EMBEDDED_URI.test(candidate))) {
+                data.keepAttr = false;
+            }
+        }
+    });
+    bodyPurifier = purifier;
+    return purifier;
+}
+
+/** Tags a displayed body may never carry, whatever else is allowed. `svg`/`math` are forbidden here too (not just
+ * on the quote path below) because this function renders a RECEIVED message's HTML — attacker-controlled content —
+ * and DOMPurify's default SVG/MathML allowlist has a history of mutation-XSS bypasses; there's no legitimate need
+ * for either in a mail body display. */
+const DISPLAY_FORBIDDEN_TAGS = ["link", "meta", "base", "svg", "math"];
+
+/**
+ * Sanitizes a message body for display (a sandboxed `srcDoc`, behind its own CSP): DOMPurify's defaults plus the
+ * remote-resource stripping above, and no `<link>`, `<meta>` or `<base>`. Returns `""` when there is no DOM to
+ * sanitize with - never the unsanitized input.
+ */
+export function sanitizeMessageBodyHtml(html: string): string {
+    return getBodyPurifier()?.sanitize(html, { FORBID_TAGS: DISPLAY_FORBIDDEN_TAGS }) ?? "";
+}
+
+/** On top of the display policy: nothing that styles, frames or submits from inside the compose editor. */
+const QUOTE_FORBIDDEN_TAGS = [
+    ...DISPLAY_FORBIDDEN_TAGS,
+    "style",
+    "title",
+    "form",
+    "input",
+    "button",
+    "select",
+    "option",
+    "textarea",
+    "iframe",
+    "frame",
+    "frameset",
+    "object",
+    "embed",
+    "audio",
+    "video",
+    "source",
+    "track",
+    // svg/math are already in DISPLAY_FORBIDDEN_TAGS, spread above — not repeated here.
+];
+
+/**
+ * Sanitizes message HTML for quoting into a compose body: the display policy (`sanitizeMessageBodyHtml()`), without
+ * the tags in `QUOTE_FORBIDDEN_TAGS`, and without any image that isn't embedded as a `data:` URI - a `cid:` image
+ * refers to a part of the original message the reply doesn't carry. Returns `""` when there is no DOM to sanitize
+ * with.
+ */
+export function sanitizeQuotedHtml(html: string): string {
+    const purifier = getBodyPurifier();
+    if (!purifier) {
+        return "";
+    }
+    const fragment = purifier.sanitize(html, { FORBID_TAGS: QUOTE_FORBIDDEN_TAGS, RETURN_DOM_FRAGMENT: true });
+    for (const image of Array.from(fragment.querySelectorAll("img"))) {
+        if (!/^\s*data:/i.test(image.getAttribute("src") ?? "")) {
+            image.remove();
+        }
+    }
+    const container = document.createElement("div");
+    container.appendChild(fragment);
+    return container.innerHTML;
+}