@rapidmx/web-client 0.30.0 → 0.32.0

package/dist/lib/contacts/preparePhoto.js

@@ -0,0 +1,250 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Gets a picture the user chose - a phone's camera photo is typically 2-8 MB, may be HEIC and carries an EXIF orientation - into what the server takes for a
+ * contact's picture (JPEG, PNG, GIF or WebP, at most `CONTACT_PHOTO_MAX_BYTES`, checked by its magic bytes), in the browser, before it is uploaded.
+ */
+import { CONTACT_PHOTO_MAX_BYTES, CONTACT_PHOTO_TYPES } from "./contactsApi.js";
+/** The longest side (in pixels) an accepted picture may have and still be sent as it is. */
+export const CONTACT_PHOTO_MAX_SIDE = 1024;
+/** The side (in pixels) of the square picture made from one that has to be changed - an avatar is shown at 72 pixels at most, 512 covers a high-density screen. */
+export const CONTACT_PHOTO_OUTPUT_SIDE = 512;
+/** JPEG qualities tried in turn until the picture fits `CONTACT_PHOTO_MAX_BYTES`. */
+export const CONTACT_PHOTO_QUALITIES = [0.85, 0.75, 0.65, 0.55, 0.45, 0.35];
+/** The most pixels (width x height) a picture may have to be decoded: a few kilobytes of PNG can say 30000 x 30000, which takes gigabytes of memory to decode. */
+export const CONTACT_PHOTO_MAX_PIXELS = 16000000;
+/** How much of the start of a picture is read to find its size: a JPEG's EXIF segment (up to 64 KB) comes before the size. */
+const HEADER_BYTES = 128 * 1024;
+export const CONTACT_PHOTO_UNSUPPORTED_MESSAGE = "This picture's format isn't supported by your browser — choose a JPEG or PNG instead.";
+export const CONTACT_PHOTO_TOO_LARGE_MESSAGE = "This picture could not be made small enough — choose another one.";
+/** Why a chosen picture cannot be used (a format the browser cannot decode, such as HEIC, or one that stays too large); its `message` is fit to show the user. */
+export class ContactPhotoError extends Error {
+    constructor(message = CONTACT_PHOTO_UNSUPPORTED_MESSAGE) {
+        super(message);
+        this.name = "ContactPhotoError";
+    }
+}
+/** How many JPEG segments are read, one small read each, past the start of a picture before giving up on finding its size. */
+const MAX_JPEG_SEGMENTS = 4096;
+/** What a JPEG segment starting at `view[0]` (`view` holds its first 9 bytes, fewer at the end of the file) says: how far to its
+ * next segment (`skip`), its size when it is the first frame header ("SOFn"), or `undefined` when there is nothing more to read -
+ * not a marker, the start of the scan, or a cut-off header. */
+function jpegSegment(view) {
+    const be16 = (offset) => (view[offset] << 8) | view[offset + 1];
+    if (view.length < 4 || view[0] !== 0xff) {
+        return undefined;
+    }
+    const marker = view[1];
+    if (marker === 0xff) {
+        return { skip: 1 };
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+        return { skip: 2 };
+    }
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return view.length >= 9 ? { width: be16(7), height: be16(5) } : undefined;
+    }
+    return marker === 0xda ? undefined : { skip: 2 + be16(2) };
+}
+/** The size of the JPEG `file`, read segment by segment from `offset` (where its start ran out) - an ICC profile or several EXIF/XMP
+ * segments can put the frame header well past the start. */
+async function jpegSizeFrom(file, offset) {
+    for (let count = 0; count < MAX_JPEG_SEGMENTS && offset < file.size; count++) {
+        const segment = jpegSegment(new Uint8Array(await file.slice(offset, offset + 9).arrayBuffer()));
+        if (!segment) {
+            return undefined;
+        }
+        if ("width" in segment) {
+            return segment;
+        }
+        offset += segment.skip;
+    }
+    return undefined;
+}
+/** What the start of a picture says about it: whether it is a JPEG, its size when that can be read from it and, for a JPEG whose
+ * start ran out before its frame header, where to read on from (`resume`). */
+function inspect(head) {
+    const at = (offset, text) => Array.from(text).every((char, i) => head[offset + i] === char.charCodeAt(0));
+    const be16 = (offset) => (head[offset] << 8) | head[offset + 1];
+    const be32 = (offset) => be16(offset) * 65536 + be16(offset + 2);
+    const le16 = (offset) => head[offset] | (head[offset + 1] << 8);
+    const le24 = (offset) => le16(offset) | (head[offset + 2] << 16);
+    const known = (width, height) => ({ jpeg: false, width, height });
+    if (at(0, "\x89PNG\r\n\x1a\n") && head.length >= 24) {
+        return known(be32(16), be32(20));
+    }
+    if (at(0, "GIF8") && head.length >= 10) {
+        return known(le16(6), le16(8));
+    }
+    if (at(0, "RIFF") && at(8, "WEBP") && head.length >= 30) {
+        if (at(12, "VP8 ")) {
+            return known(le16(26) & 0x3fff, le16(28) & 0x3fff);
+        }
+        if (at(12, "VP8L")) {
+            const bits = (le16(21) | (le16(23) << 16)) >>> 0;
+            return known((bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+        }
+        if (at(12, "VP8X")) {
+            return known(le24(24) + 1, le24(27) + 1);
+        }
+        return { jpeg: false };
+    }
+    if (!(head[0] === 0xff && head[1] === 0xd8)) {
+        return { jpeg: false };
+    }
+    // A JPEG is a run of segments (`FF marker`, then a length unless the marker stands alone); the size is in the first frame header, "SOFn".
+    let offset = 2;
+    while (offset + 4 <= head.length) {
+        const segment = jpegSegment(head.subarray(offset, offset + 9));
+        if (!segment) {
+            return { jpeg: true };
+        }
+        if ("width" in segment) {
+            return { jpeg: true, ...segment };
+        }
+        offset += segment.skip;
+    }
+    return { jpeg: true, resume: offset };
+}
+/** Decodes with the orientation of the photo's EXIF applied, so a phone's sideways-stored picture comes out upright. */
+async function decode(file) {
+    if (typeof createImageBitmap === "function") {
+        try {
+            const bitmap = await createImageBitmap(file, { imageOrientation: "from-image" });
+            return { source: bitmap, width: bitmap.width, height: bitmap.height, release: () => bitmap.close() };
+        }
+        catch {
+            // Fall through: an `<img>` may still read what this `createImageBitmap()` would not.
+        }
+    }
+    // An `<img>` applies the EXIF orientation itself (`image-orientation: from-image` is the default).
+    const url = URL.createObjectURL(file);
+    try {
+        const image = await new Promise((resolve, reject) => {
+            const element = new Image();
+            element.onload = () => resolve(element);
+            element.onerror = () => reject(new ContactPhotoError());
+            element.src = url;
+        });
+        return { source: image, width: image.naturalWidth, height: image.naturalHeight, release: () => undefined };
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}
+function createSurface(side) {
+    if (typeof OffscreenCanvas === "function") {
+        const canvas = new OffscreenCanvas(side, side);
+        const context = canvas.getContext("2d");
+        if (!context) {
+            throw new ContactPhotoError();
+        }
+        return { context, encode: (type, quality) => canvas.convertToBlob({ type, quality }) };
+    }
+    const canvas = document.createElement("canvas");
+    canvas.width = side;
+    canvas.height = side;
+    const context = canvas.getContext("2d");
+    if (!context) {
+        throw new ContactPhotoError();
+    }
+    return { context, encode: (type, quality) => new Promise((resolve) => canvas.toBlob(resolve, type, quality)) };
+}
+function hasTransparency(context, side) {
+    const { data } = context.getImageData(0, 0, side, side);
+    for (let i = 3; i < data.length; i += 4) {
+        if (data[i] < 255) {
+            return true;
+        }
+    }
+    return false;
+}
+function renamed(name, extension) {
+    return `${name.replace(/\.[^./\\]*$/, "") || "photo"}.${extension}`;
+}
+/**
+ * The picture to upload for `file`. A picture the server already takes (an accepted type within the byte limit and at most `CONTACT_PHOTO_MAX_SIDE` pixels a
+ * side) is returned as it is - an animated GIF stays animated - unless it is a JPEG, which is always drawn again to drop its EXIF. Anything else (a phone's 6 MB photo, a HEIC, a huge PNG) is decoded with its EXIF orientation applied,
+ * cropped to the centered square - avatars are circular, so the corners are never seen - scaled down to at most `CONTACT_PHOTO_OUTPUT_SIDE` pixels and encoded as a
+ * JPEG (transparent parts on white, quality lowered step by step until it fits), or kept as PNG/WebP when it has transparency and still fits.
+ *
+ * @throws ContactPhotoError when the browser cannot decode it (HEIC, or not a picture at all), it says it has more than `CONTACT_PHOTO_MAX_PIXELS` pixels
+ * (it is not decoded at all then) or it cannot be made small enough.
+ */
+export async function prepareContactPhoto(file) {
+    const accepted = CONTACT_PHOTO_TYPES.includes(file.type) && file.size <= CONTACT_PHOTO_MAX_BYTES;
+    let head = inspect(new Uint8Array(await file.slice(0, HEADER_BYTES).arrayBuffer()));
+    if (head.resume !== undefined) {
+        head = { ...head, ...(await jpegSizeFrom(file, head.resume)) };
+    }
+    if (head.jpeg && (!head.width || !head.height)) {
+        // A JPEG whose size is not found within the segments read (or is given as zero, to be redefined by a later marker) could be of any
+        // size, and would reach the decoder unchecked.
+        throw new ContactPhotoError();
+    }
+    if (head.width !== undefined && head.height !== undefined && head.width * head.height > CONTACT_PHOTO_MAX_PIXELS) {
+        throw new ContactPhotoError(CONTACT_PHOTO_TOO_LARGE_MESSAGE);
+    }
+    // A JPEG is always drawn again: its EXIF (the camera, the time, often where it was taken) would otherwise be uploaded and shown to whoever sees the contact.
+    const jpeg = head.jpeg || file.type === "image/jpeg";
+    let decoded;
+    try {
+        decoded = await decode(file);
+    }
+    catch (err) {
+        if (accepted && !jpeg) {
+            // It cannot be measured here but the server takes it as it is.
+            return file;
+        }
+        throw err;
+    }
+    try {
+        const { source, width, height } = decoded;
+        // The size could not be read from the file itself (a format with no reader above, or a size past the segments read): what
+        // the decoder made of it is the last check before it is drawn.
+        if (width * height > CONTACT_PHOTO_MAX_PIXELS) {
+            throw new ContactPhotoError(CONTACT_PHOTO_TOO_LARGE_MESSAGE);
+        }
+        if (accepted && !jpeg && Math.max(width, height) <= CONTACT_PHOTO_MAX_SIDE) {
+            return file;
+        }
+        const crop = Math.min(width, height);
+        // Never enlarged: a small picture only gets cropped.
+        const side = Math.min(crop, CONTACT_PHOTO_OUTPUT_SIDE);
+        const { context, encode } = createSurface(side);
+        const draw = () => {
+            context.imageSmoothingQuality = "high";
+            context.drawImage(source, (width - crop) / 2, (height - crop) / 2, crop, crop, 0, 0, side, side);
+        };
+        draw();
+        if (["image/png", "image/webp", "image/gif"].includes(file.type) && hasTransparency(context, side)) {
+            const type = file.type === "image/webp" ? "image/webp" : "image/png";
+            const blob = await encode(type);
+            if (blob && blob.size <= CONTACT_PHOTO_MAX_BYTES) {
+                // A browser that cannot encode WebP answers with a PNG instead.
+                const kept = blob.type || type;
+                return new File([blob], renamed(file.name, kept === "image/webp" ? "webp" : "png"), { type: kept });
+            }
+            // Too large to keep the transparency: a JPEG has none, so what showed through becomes white.
+            context.clearRect(0, 0, side, side);
+        }
+        context.fillStyle = "#ffffff";
+        context.fillRect(0, 0, side, side);
+        draw();
+        for (const quality of CONTACT_PHOTO_QUALITIES) {
+            const blob = await encode("image/jpeg", quality);
+            if (!blob) {
+                throw new ContactPhotoError();
+            }
+            if (blob.size <= CONTACT_PHOTO_MAX_BYTES) {
+                return new File([blob], renamed(file.name, "jpg"), { type: "image/jpeg" });
+            }
+        }
+        throw new ContactPhotoError(CONTACT_PHOTO_TOO_LARGE_MESSAGE);
+    }
+    finally {
+        decoded.release();
+    }
+}

package/dist/lib/contacts/useContactPhotoSrc.d.ts

@@ -0,0 +1,19 @@
+import type { ApiClient } from "../util/api.js";
+import { type Contact } from "./contactsApi.js";
+/** Forgets every cached picture (and revokes its URL). For a test, or when an account is signed out. */
+export declare function clearContactPhotoCache(): void;
+/**
+ * What to put in an `<img src>` for a contact's own picture, or `undefined` when they have none, it is still loading or it could not be loaded (the avatar
+ * then shows initials). Without an explicit `client` that is the plain `contactPhotoUrl()`: the browser sends the `jwt` cookie with the request. A
+ * token-authenticated client (the desktop and mobile apps) cannot do that - an `<img>` sends no `Authorization` header - so the picture is fetched through the client
+ * and shown as a `blob:` URL, cached per client, contact and version with a small LRU and revoked once it falls out of it and nothing shows it.
+ */
+export declare function useContactPhotoSrc(contact: Pick<Contact, "uid" | "version" | "photoBlobKey"> | undefined, client?: ApiClient): string | undefined;
+/**
+ * `useContactPhotoSrc()`, also saying whether a picture that has to be fetched could not be (`failed`: no `src` is coming), and held back until `active` - an avatar
+ * that is not on screen yet has no reason to fetch its picture.
+ */
+export declare function useContactPhoto(contact: Pick<Contact, "uid" | "version" | "photoBlobKey"> | undefined, client?: ApiClient, active?: boolean): {
+    src: string | undefined;
+    failed: boolean;
+};

package/dist/lib/contacts/useContactPhotoSrc.js

@@ -0,0 +1,153 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { contactPhotoUrl, fetchContactPhoto } from "./contactsApi.js";
+/** How many pictures stay loaded (as `blob:` URLs) after nothing shows them any more, so a list scrolled back over does not fetch them all again. */
+const CACHE_LIMIT = 50;
+/** Least recently used first (a `Map` iterates in insertion order, and a use moves the entry to the end). */
+const entries = new Map();
+/** Fetches in flight, and how many avatars are waiting on each (they are all counted as showing the picture the moment it is stored). */
+const pending = new Map();
+const clientIds = new WeakMap();
+let nextClientId = 0;
+/** One key per picture of one account: the same uid never collides across the clients of a multi-account app, and a replaced picture (new version) is a new key. */
+function keyOf(client, uid, version) {
+    let id = clientIds.get(client);
+    if (id === undefined) {
+        id = nextClientId++;
+        clientIds.set(client, id);
+    }
+    return `${id}:${uid}:${version}`;
+}
+/** Revokes the pictures beyond the limit that nothing shows, oldest first. */
+function trim() {
+    for (const [key, entry] of entries) {
+        if (entries.size <= CACHE_LIMIT) {
+            return;
+        }
+        if (entry.refs === 0) {
+            URL.revokeObjectURL(entry.url);
+            entries.delete(key);
+        }
+    }
+}
+/** How many pictures are fetched at once; a list of a hundred contacts must not open a hundred requests together. */
+const MAX_CONCURRENT_FETCHES = 4;
+let fetching = 0;
+const waiting = [];
+/** Runs `task` once fewer than `MAX_CONCURRENT_FETCHES` others are running, in the order asked. */
+function limited(task) {
+    return new Promise((resolve, reject) => {
+        const run = () => {
+            task()
+                .then(resolve, reject)
+                .finally(() => {
+                // A waiting task takes over the slot; it is only given up when none waits.
+                const next = waiting.shift();
+                if (next) {
+                    next();
+                }
+                else {
+                    fetching--;
+                }
+            });
+        };
+        if (fetching < MAX_CONCURRENT_FETCHES) {
+            fetching++;
+            run();
+        }
+        else {
+            waiting.push(run);
+        }
+    });
+}
+/** The `blob:` URL for `key`, fetched with `load` unless it is cached, and counted as shown until `release()`. Concurrent callers share one fetch. */
+async function acquire(key, load) {
+    const entry = entries.get(key);
+    if (entry) {
+        entry.refs++;
+        entries.delete(key);
+        entries.set(key, entry);
+        return entry.url;
+    }
+    let shared = pending.get(key);
+    if (!shared) {
+        const created = {
+            waiters: 0,
+            request: limited(load)
+                .then((blob) => {
+                const url = URL.createObjectURL(blob);
+                // Claimed by everyone waiting from the start: an entry nobody holds yet could be trimmed before its avatar got to it.
+                entries.set(key, { url, refs: created.waiters });
+                return url;
+            })
+                .finally(() => pending.delete(key)),
+        };
+        pending.set(key, created);
+        shared = created;
+    }
+    shared.waiters++;
+    return shared.request;
+}
+function release(key) {
+    const entry = entries.get(key);
+    if (entry) {
+        entry.refs--;
+    }
+    trim();
+}
+/** Forgets every cached picture (and revokes its URL). For a test, or when an account is signed out. */
+export function clearContactPhotoCache() {
+    for (const entry of entries.values()) {
+        URL.revokeObjectURL(entry.url);
+    }
+    entries.clear();
+}
+/**
+ * What to put in an `<img src>` for a contact's own picture, or `undefined` when they have none, it is still loading or it could not be loaded (the avatar
+ * then shows initials). Without an explicit `client` that is the plain `contactPhotoUrl()`: the browser sends the `jwt` cookie with the request. A
+ * token-authenticated client (the desktop and mobile apps) cannot do that - an `<img>` sends no `Authorization` header - so the picture is fetched through the client
+ * and shown as a `blob:` URL, cached per client, contact and version with a small LRU and revoked once it falls out of it and nothing shows it.
+ */
+export function useContactPhotoSrc(contact, client) {
+    return useContactPhoto(contact, client).src;
+}
+/**
+ * `useContactPhotoSrc()`, also saying whether a picture that has to be fetched could not be (`failed`: no `src` is coming), and held back until `active` - an avatar
+ * that is not on screen yet has no reason to fetch its picture.
+ */
+export function useContactPhoto(contact, client, active = true) {
+    const [loaded, setLoaded] = useState();
+    const [failedKey, setFailedKey] = useState();
+    const key = active && client && contact?.photoBlobKey ? keyOf(client, contact.uid, contact.version) : undefined;
+    const uid = contact?.uid;
+    const version = contact?.version;
+    useEffect(() => {
+        if (!key || !client) {
+            return;
+        }
+        let cancelled = false;
+        let held = false;
+        acquire(key, () => fetchContactPhoto(uid, version, client)).then((url) => {
+            if (cancelled) {
+                release(key);
+            }
+            else {
+                held = true;
+                setLoaded({ key, url });
+            }
+        }, () => !cancelled && setFailedKey(key));
+        return () => {
+            cancelled = true;
+            if (held) {
+                release(key);
+            }
+        };
+    }, [key]);
+    if (client) {
+        return { src: key !== undefined && loaded?.key === key ? loaded.url : undefined, failed: key !== undefined && failedKey === key };
+    }
+    return { src: contact && contactPhotoUrl(contact), failed: false };
+}

package/dist/lib/contacts/vcard.d.ts

@@ -12,6 +12,9 @@ export declare function contactsToVCardFile(contacts: Contact[]): string;
 /** 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">;
+/** How much of a file's text `parseVCards()` reads, and how many records it takes from it (the rest is ignored). */
+export declare const VCARD_MAX_CHARS = 5000000;
+export declare const VCARD_MAX_CONTACTS = 2000;
 /**
  * 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

package/dist/lib/contacts/vcard.js

@@ -86,6 +86,47 @@ function valueSeparatorIndex(line) {
     }
     return -1;
 }
+/** How much of a file's text `parseVCards()` reads, and how many records it takes from it (the rest is ignored). */
+export const VCARD_MAX_CHARS = 5000000;
+export const VCARD_MAX_CONTACTS = 2000;
+/** Decodes a quoted-printable value: each `=XX` is one byte, and the bytes are text in `charset` (UTF-8 when none is named or the name is unknown). */
+function decodeQuotedPrintable(value, charset) {
+    const encoder = new TextEncoder();
+    const bytes = [];
+    for (const [, hex, literal] of value.matchAll(/=([0-9a-f]{2})|([\s\S])/giu)) {
+        if (hex) {
+            bytes.push(parseInt(hex, 16));
+        }
+        else {
+            bytes.push(...encoder.encode(literal));
+        }
+    }
+    try {
+        return new TextDecoder(charset || "utf-8").decode(new Uint8Array(bytes));
+    }
+    catch {
+        return new TextDecoder().decode(new Uint8Array(bytes));
+    }
+}
+/** `lines` with each quoted-printable line that ends in `=` (a soft line break) joined to the line that carries on from it. */
+function joinQuotedPrintableLines(lines) {
+    const joined = [];
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i];
+        if (/^[^:]*QUOTED-PRINTABLE/i.test(line)) {
+            // Collected and joined once: appending to a growing string a line at a time is quadratic in a value of many soft breaks.
+            const parts = [];
+            while (line.endsWith("=") && i + 1 < lines.length) {
+                parts.push(line.slice(0, -1));
+                line = lines[++i];
+            }
+            parts.push(line);
+            line = parts.join("");
+        }
+        joined.push(line);
+    }
+    return joined;
+}
 /**
  * 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:`)
@@ -115,13 +156,15 @@ function normalizeType(params) {
  * `normalizeType()`); structured values are split on unescaped `;` only.
  */
 export function parseVCards(text) {
+    // A file is read only so far: nothing legitimate is this large, and a huge one would be minutes of parsing and thousands of records.
+    const source = text.length > VCARD_MAX_CHARS ? text.slice(0, VCARD_MAX_CHARS) : text;
     // 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);
+    const unfolded = source.replace(/(?:\r\n|\r|\n)[ \t]/g, "");
+    const cards = unfolded.split(/^[ \t]*BEGIN:VCARD[ \t]*$/im).slice(1, VCARD_MAX_CONTACTS + 1);
     return cards.map((card) => {
         const contact = { displayName: "", emails: [], phones: [], addresses: [] };
-        const lines = card.split(/\r\n|\r|\n/);
+        const lines = joinQuotedPrintableLines(card.split(/\r\n|\r|\n/));
         for (const rawLine of lines) {
             const line = rawLine.trim();
             const colonIndex = valueSeparatorIndex(line);
@@ -129,9 +172,13 @@ export function parseVCards(text) {
                 continue;
             }
             const key = line.slice(0, colonIndex);
-            const rawValue = line.slice(colonIndex + 1);
-            const value = unescapeVCardValue(rawValue);
             const [groupedName, ...params] = key.split(";");
+            // vCard 2.1 may encode a value as quoted-printable (`ENCODING=QUOTED-PRINTABLE`, or the bare parameter), in a named charset;
+            // such a value has no backslash escapes.
+            const quotedPrintable = params.some((param) => /^(?:ENCODING=)?QUOTED-PRINTABLE$/i.test(param.trim()));
+            const charset = params.find((param) => /^CHARSET=/i.test(param.trim()))?.trim().slice("CHARSET=".length).replace(/"/g, "");
+            const rawValue = quotedPrintable ? decodeQuotedPrintable(line.slice(colonIndex + 1), charset) : line.slice(colonIndex + 1);
+            const value = quotedPrintable ? rawValue : unescapeVCardValue(rawValue);
             const name = groupedName.slice(groupedName.lastIndexOf(".") + 1).toUpperCase();
             const type = normalizeType(params);
             switch (name) {
@@ -154,10 +201,15 @@ export function parseVCards(text) {
                     contact.jobTitle = value;
                     break;
                 case "EMAIL":
-                    contact.emails.push({ address: value, type });
+                    // An empty one would make the server refuse the whole contact.
+                    if (value.trim()) {
+                        contact.emails.push({ address: value.trim(), type });
+                    }
                     break;
                 case "TEL":
-                    contact.phones.push({ phoneNumber: value, type });
+                    if (value.trim()) {
+                        contact.phones.push({ phoneNumber: value, type });
+                    }
                     break;
                 case "ADR": {
                     const [, , street, city, state, postalCode, country] = splitStructuredValue(rawValue);

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

@@ -18,6 +18,14 @@ export interface GeneratedEscrowKeys {
     /** Ready to pass as `createEscrowScope()`'s `publicKey`. */
     publicKey: EscrowScopePublicKey;
 }
+/**
+ * The SHA-256 fingerprint (lower-case hex, as `computeCertFingerprint()` gives it) of the certificate that `publicKey` - an escrow scope's pasted public key,
+ * the base64 of its DER - holds, or `null` when it is not a certificate. The holders compare a scope's fingerprint out of band, so one typed beside a
+ * different key makes that check worthless: this is what it has to be.
+ */
+export declare function escrowPublicKeyFingerprint(publicKey: string): Promise<string | null>;
+/** A fingerprint as `escrowPublicKeyFingerprint()` writes it: lower-case hex only, whatever separators (`AB:CD`, spaces) it was typed with. */
+export declare function normalizeFingerprint(fingerprint: string): string;
 export declare function generateEscrowKeyPair(options: {
     name: string;
     validDays: number;

package/dist/lib/crypto/escrowKeys.js

@@ -14,10 +14,29 @@
  */
 import "reflect-metadata";
 import * as x509 from "@peculiar/x509";
-import { toBase64 } from "./encoding.js";
+import { fromBase64, toBase64 } from "./encoding.js";
 import { computeCertFingerprint } from "./smime.js";
 x509.cryptoProvider.set(crypto);
 const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * The SHA-256 fingerprint (lower-case hex, as `computeCertFingerprint()` gives it) of the certificate that `publicKey` - an escrow scope's pasted public key,
+ * the base64 of its DER - holds, or `null` when it is not a certificate. The holders compare a scope's fingerprint out of band, so one typed beside a
+ * different key makes that check worthless: this is what it has to be.
+ */
+export async function escrowPublicKeyFingerprint(publicKey) {
+    try {
+        const der = fromBase64(publicKey.trim());
+        void new x509.X509Certificate(new Uint8Array(der));
+        return await computeCertFingerprint(der);
+    }
+    catch {
+        return null;
+    }
+}
+/** A fingerprint as `escrowPublicKeyFingerprint()` writes it: lower-case hex only, whatever separators (`AB:CD`, spaces) it was typed with. */
+export function normalizeFingerprint(fingerprint) {
+    return fingerprint.replace(/[^0-9a-f]/gi, "").toLowerCase();
+}
 function toPem(label, der) {
     const lines = toBase64(der).match(/.{1,64}/g) ?? [];
     return `-----BEGIN ${label}-----\n${lines.join("\n")}\n-----END ${label}-----\n`;

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

@@ -102,8 +102,11 @@ export interface MessageSecurityResult {
      * recovered and it carried a protected Subject. */
     subject?: string;
     /** Every protected header recovered from inside the signed/decrypted entity - present only when that entity
-     * carries RFC 9788 protected headers (a protected `From`). Absent for a legacy S/MIME sender's signed-only
-     * message: its outer Subject/To/Cc were then never signed, and a UI should not present them as verified. */
+     * carries RFC 9788 protected headers (a protected `From`) AND a signature over them verified (so also for a
+     * `"verified_at_first_open"` result). Absent for a legacy S/MIME sender's signed-only message (its outer
+     * Subject/To/Cc were then never signed, and a UI should not present them as verified), and for an encrypted
+     * message without a verified signature: anyone holding the reader's public certificate can encrypt headers of their
+     * own choosing, so they are never exposed. */
     protectedHeaders?: MessageProtectedHeaders;
     /** The attachments inside the verified/decrypted entity - for a signed-only message the only attachments the
      * signature covers, so a UI showing a verified badge should list these rather than the server's attachment
@@ -149,7 +152,7 @@ export interface SignerBindingInput {
     /** The certificate matched to the verified SignerInfo; `undefined` fails closed. */
     signerCertificateDer: Uint8Array | undefined;
     /** Headers recovered from inside the signed content (RFC 9788), if any. */
-    protectedHeaders: (Pick<ProtectedHeaders, "from" | "to"> & Partial<Pick<ProtectedHeaders, "cc" | "subject">>) | undefined;
+    protectedHeaders: (Pick<ProtectedHeaders, "from" | "to"> & Partial<Pick<ProtectedHeaders, "cc" | "subject" | "date">>) | undefined;
     /** The received message's outer header map (lowercased names), as `parseMimeEntity()` returns it. */
     outerHeaders: Record<string, string>;
     /** Every outer header field in order (`parseMimeEntity()`'s `fields`) - checked for repeated
@@ -159,7 +162,7 @@ export interface SignerBindingInput {
     protectedFields?: MimeHeaderField[];
     /** One trusted fingerprint or several (any match is accepted). An empty array counts as none supplied. */
     pinnedSignerFingerprint?: string | string[];
-    /** Also require the protected `Subject` (when protected headers are present) to equal the outer one - right for
+    /** Also require the protected `Subject` and `Date` (when protected headers are present) to equal the outer ones - right for
      * a signed-only (`hp="clear"`) message, wrong for an encrypted one whose outer Subject is obscured. */
     compareSubject?: boolean;
 }