@rapidmx/web-client 0.35.0 → 0.37.0

package/lib/crypto/messageSecurity.ts

@@ -37,10 +37,36 @@
  * `untrusted_signer`. Previously pinned keys count as pins (see `signingKeyFingerprints()`), so mail signed before an
  * accepted or automatic rotation still verifies.
  */
-import { DisplayBody, MimeAttachment, MimeHeaderField, decodeHeaderText, extractAddresses, parseMimeEntity, parseParameterizedHeader, plainTextToHtml } from "./mime.js";
-import { toBase64 } from "./encoding.js";
-import { computeCertFingerprint, extractCertificateEmails } from "./smime.js";
-import { ComparableOuterHeaders, ProtectedHeaders, parseEncryptedMessageWithKeys, parseSignedOnlyMessage } from "./smimeMessage.js";
+import {
+    DisplayBody,
+    MimeAttachment,
+    MimeHeaderField,
+    bytesToBinaryString,
+    decodeBodyText,
+    type MimeEntity,
+    decodeBase64Text,
+    decodeHeaderText,
+    extractAddresses,
+    extractAttachments,
+    extractCalendarText,
+    extractDisplayBody,
+    parseMimeEntity,
+    parseParameterizedHeader,
+    plainTextToHtml,
+} from "./mime.js";
+import { fromBase64, toBase64 } from "./encoding.js";
+import { type DecryptionKey, computeCertFingerprint, decryptEnvelopedDataWithKeys, extractCertificateEmails } from "./smime.js";
+import {
+    ComparableOuterHeaders,
+    ProtectedHeaders,
+    extractHpOuterHeaders,
+    headersToProtectedHeaders,
+    outerHeadersMatch,
+    parseEncryptedMessageWithKeys,
+    parseSignedOnlyMessage,
+} from "./smimeMessage.js";
+import type { OpenPgpPrivateKey } from "./openpgp.js";
+import type { ParsedPgpMessage, PgpSignerCandidate } from "./pgpMessage.js";
 import { type PublicKey, isTrustedForVerification } from "./keyvaultApi.js";
 import { KeysLockedError } from "./masterKey.js";
 import { type SealKeyMaterial, type SealedVerificationState, buildVerificationSeal, openVerificationSeal, rawMimeSha256 } from "./verificationSeal.js";
@@ -67,6 +93,7 @@ export type MessageSecurityState =
     | "encrypted_unverified_signer"
     | "signature_failed"
     | "verified_at_first_open"
+    | "protected_at_rest"
     | "unprotected";
 
 /** Why a message is `"signature_failed"`. `invalid_signature`: the CMS signature itself is malformed or
@@ -113,6 +140,13 @@ export interface MessageSecurityResult {
      * since-rotated key, non-AEAD content encryption, or corrupt/foreign data) - the caller should keep
      * showing whatever `GET /:id/content` already produced alongside this explanation. */
     decryptError?: string;
+    /** Set when the stored message was sealed at rest by the server (restapi `specs/search.md` §3) and opened here with the mailbox's
+     * zero-access key. `state` then describes the original message inside: `protected_at_rest` when it arrived unprotected, or its own
+     * signed/encrypted state otherwise. */
+    zeroAccess?: boolean;
+    /** With `zeroAccess`: the original's calendar file (`extractCalendarText()`), which the server can't read from the sealed copy - the
+     * client sends it with the invitation endpoints. Absent when the message carries none. */
+    calendar?: string;
     /** See `ParsedEncryptedMessage.headerTamperDetected`'s own doc comment - a deliberately separate,
      * orthogonal signal from `state`, since RFC 9788's `HP-Outer` is written on every encrypted message
      * regardless of whether it's also signed. `undefined` for anything that isn't an encrypted message
@@ -139,6 +173,14 @@ export interface MessageSecurityResult {
     signerFingerprint?: string;
     /** The email addresses that signer certificate asserts (lowercased), alongside `signerFingerprint`. */
     signerEmails?: string[];
+    /** `"openpgp"` when the signer is an OpenPGP key: `signerCertificate` is then its certificate (base64 binary) and
+     * `signerFingerprint` its primary key's fingerprint - pin it with `trustSigner()`'s `type: "openpgp"`. */
+    signerKeyType?: "openpgp";
+    /** `true` for an OpenPGP message whose signature was made by a key this reader doesn't have (neither pinned for the sender,
+     * nor the reader's own, nor attached to the message), so it couldn't be checked at all. A signed-only one is then reported
+     * `"unprotected"` (its content is readable anyway), an encrypted one `"encrypted"`; a UI can say the sender's key isn't known
+     * yet. */
+    signerKeyUnknown?: boolean;
     /** Base64 DER of the certificate that verified the signature - what `keyvaultApi.ts`'s `trustSigner()` pins for
      * a "trust this signer" action. Present alongside `signerFingerprint` for `"signed_verified"`,
      * `"encrypted_verified"`, the `*_unverified_signer` states, and `"signature_failed"` with reason
@@ -258,8 +300,13 @@ function sameInstant(signed: string | undefined, outer: string | undefined): boo
     return Number.isNaN(left) || left === Date.parse(String(outer));
 }
 
-function normalizePins(pins: string | string[] | undefined): string[] {
-    return (Array.isArray(pins) ? pins : pins === undefined ? [] : [pins]).map((pin) => pin.toLowerCase());
+function normalizePins(pins: SignerPinsInput): string[] {
+    const list: string[] = Array.isArray(pins) ? pins : pins === undefined ? [] : typeof pins === "string" ? [pins] : pins.fingerprints;
+    return list.map((pin) => pin.toLowerCase());
+}
+
+function pinnedOpenPgpKeys(pins: SignerPinsInput): string[] {
+    return pins !== undefined && typeof pins === "object" && !Array.isArray(pins) ? pins.openPgpKeys : [];
 }
 
 /** Checks 2-4 from this module's doc comment for an already cryptographically verified signature.
@@ -277,13 +324,14 @@ export async function checkSignerBinding(input: SignerBindingInput): Promise<Sig
     if (pins.length > 0 && !pins.includes(await computeCertFingerprint(certDer))) {
         // A certificate that otherwise binds cleanly to the sender is a key change for the user to judge; anything else
         // (no certificate, wrong identity, header tampering) stays a plain untrusted signer.
-        return input.signerCertificateDer && checkIdentityAndHeaders(input, certDer) === undefined ? "signer_key_changed" : "untrusted_signer";
+        return input.signerCertificateDer && checkIdentityAndHeaders(input, extractCertificateEmails(certDer)) === undefined ? "signer_key_changed" : "untrusted_signer";
     }
-    return checkIdentityAndHeaders(input, certDer);
+    return checkIdentityAndHeaders(input, extractCertificateEmails(certDer));
 }
 
-/** Checks 3-4 from this module's doc comment. */
-function checkIdentityAndHeaders(input: SignerBindingInput, certDer: Uint8Array): SignatureFailureReason | undefined {
+/** Checks 3-4 from this module's doc comment, for a signer whose key names `signerEmails` (an X.509 certificate's, or an
+ * OpenPGP key's user IDs). */
+function checkIdentityAndHeaders(input: Omit<SignerBindingInput, "signerCertificateDer">, signerEmails: string[]): SignatureFailureReason | undefined {
     const { protectedHeaders, outerHeaders } = input;
     if (hasRepeatedAddressField(input.outerFields) || hasRepeatedAddressField(input.protectedFields)) {
         return "header_mismatch";
@@ -291,7 +339,7 @@ function checkIdentityAndHeaders(input: SignerBindingInput, certDer: Uint8Array)
     const outerFrom = extractAddresses(outerHeaders["from"]);
     const protectedFrom = extractAddresses(protectedHeaders?.from);
     const senderAddresses = protectedFrom.length > 0 ? protectedFrom : outerFrom;
-    if (senderAddresses.length !== 1 || !extractCertificateEmails(certDer).includes(senderAddresses[0])) {
+    if (senderAddresses.length !== 1 || !signerEmails.includes(senderAddresses[0])) {
         return "signer_identity_mismatch";
     }
     const protectedTo = extractAddresses(protectedHeaders?.to);
@@ -335,7 +383,7 @@ function checkIdentityAndHeaders(input: SignerBindingInput, certDer: Uint8Array)
 export async function evaluateMessageSecurity(
     rawMime: string,
     unlocked: MessageSecurityKeys | undefined,
-    pinnedSignerFingerprints?: string | string[],
+    pinnedSignerFingerprints?: SignerPinsInput,
     readerAddress?: string,
 ): Promise<MessageSecurityResult> {
     return (await evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress)).result;
@@ -347,6 +395,75 @@ export interface MessageSecurityKeys {
     encryptionCertDer?: Uint8Array;
     retainedEncryptionKeys?: { certDer: Uint8Array; privateKey: CryptoKey }[];
     signingFingerprint?: string;
+    /** The mailbox's zero-access keys (`keySession.ts`'s `UnlockedKeys.zeroAccessKeys`) - what opens a message the server sealed at
+     * rest on arrival. */
+    zeroAccessKeys?: { certDer: Uint8Array; privateKey: CryptoKey }[];
+    /** The mailbox's OpenPGP secret keys (`keySession.ts`'s `UnlockedKeys.openPgpKeys`), the active one first - what opens mail an
+     * OpenPGP user encrypted to the mailbox, and verifies mail it signed itself. */
+    openPgpKeys?: { fingerprint: string; privateKey: OpenPgpPrivateKey }[];
+}
+
+/** The sender's trusted keys, when they include OpenPGP certificates: `fingerprints` as `pinnedSignerFingerprints`, and
+ * `openPgpKeys` the pinned OpenPGP certificates themselves (base64, `PublicKey.publicKey`) - an OpenPGP signature carries only
+ * a key ID, so its key has to be supplied to be checked at all (`pinnedSigners.ts`'s `getPinnedSigners()`). */
+export interface SignerPins {
+    fingerprints: string[];
+    openPgpKeys: string[];
+}
+
+/** What `pinnedSignerFingerprints` accepts: one fingerprint, several, or `SignerPins`. */
+export type SignerPinsInput = string | string[] | SignerPins | undefined;
+
+/**
+ * The subject and preview of a zero-access message (`Message.zeroAccess.sealedSummary`, base64 CMS of JSON `{ subject, preview }`),
+ * decrypted with the mailbox's zero-access keys - a few hundred bytes, so a message list shows real subjects without downloading
+ * each message. `undefined` when no key opens it or it isn't a summary.
+ */
+export async function openZeroAccessSummary(
+    sealedSummary: string,
+    keys: DecryptionKey[] | undefined,
+): Promise<{ subject: string; preview: string } | undefined> {
+    if (!keys?.length) {
+        return undefined;
+    }
+    try {
+        const json: unknown = JSON.parse(new TextDecoder().decode(await decryptEnvelopedDataWithKeys(fromBase64(sealedSummary), keys)));
+        const { subject, preview } = (json ?? {}) as Record<string, unknown>;
+        return typeof subject === "string" && typeof preview === "string" ? { subject, preview } : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * The original MIME (as a binary string) of a stored message the server sealed at rest, opened with `unlocked.zeroAccessKeys` -
+ * `undefined` when it isn't a sealed message or no key opens it. For what needs the original itself, e.g. reporting it to the spam
+ * filter (`reportMessage()`'s `rawMessage`).
+ */
+export async function openZeroAccessMessage(rawMime: string, unlocked: MessageSecurityKeys | undefined): Promise<string | undefined> {
+    const { headers, body } = parseMimeEntity(rawMime);
+    const rawContentType = headers["content-type"];
+    if (!unlocked?.zeroAccessKeys?.length || !rawContentType || !isEncryptedContentType(parseParameterizedHeader(rawContentType))) {
+        return undefined;
+    }
+    return openZeroAccess(body, unlocked.zeroAccessKeys);
+}
+
+/**
+ * The original MIME of a message the server sealed at rest (restapi `specs/search.md` §3) - the stored S/MIME `enveloped-data`
+ * message's content, decrypted with one of `keys` - or `undefined` when none of them opens it. Only the server ever encrypts to a
+ * zero-access key (it is never published), so a message that opens with one was sealed at rest, never sent end-to-end.
+ */
+async function openZeroAccess(body: string, keys: DecryptionKey[]): Promise<string | undefined> {
+    const der = decodeBase64Text(body);
+    if (!der) {
+        return undefined;
+    }
+    try {
+        return bytesToBinaryString(await decryptEnvelopedDataWithKeys(der, keys));
+    } catch {
+        return undefined;
+    }
 }
 
 /** `evaluateMessageSecurity()`'s result plus what the seal-aware wrapper needs: which kind of protected message it was,
@@ -360,15 +477,21 @@ interface LiveEvaluation {
 async function evaluateLive(
     rawMime: string,
     unlocked: MessageSecurityKeys | undefined,
-    pinnedSignerFingerprints: string | string[] | undefined,
+    pinnedSignerFingerprints: SignerPinsInput,
     readerAddress: string | undefined,
+    sealedAtRest = false,
 ): Promise<LiveEvaluation> {
-    const { headers, body, fields } = parseMimeEntity(rawMime);
+    const outerEntity = parseMimeEntity(rawMime);
+    const { headers, body, fields } = outerEntity;
     const rawContentType = headers["content-type"];
+    const contentType = parseParameterizedHeader(rawContentType ?? "text/plain");
+    const pgp = pgpKind(contentType, outerEntity);
+    if (pgp) {
+        return await evaluatePgp(pgp, rawContentType ?? "text/plain", outerEntity, unlocked, pinnedSignerFingerprints, readerAddress);
+    }
     if (!rawContentType) {
         return { result: { state: "unprotected" }, kind: "other" };
     }
-    const contentType = parseParameterizedHeader(rawContentType);
     const callerPins = normalizePins(pinnedSignerFingerprints);
 
     // The received message's own *real* outer envelope - what `HP-Outer`'s field copies (written at
@@ -452,6 +575,35 @@ async function evaluateLive(
         };
     }
 
+    // A message the server sealed at rest: evaluate the original it holds - which may itself be signed or end-to-end encrypted -
+    // and report one that was unprotected when it arrived as `protected_at_rest`, with its content.
+    if (isEncryptedContentType(contentType) && !sealedAtRest && unlocked?.zeroAccessKeys?.length) {
+        const original = await openZeroAccess(body, unlocked.zeroAccessKeys);
+        if (original !== undefined) {
+            const inner = await evaluateLive(original, unlocked, pinnedSignerFingerprints, readerAddress, true);
+            const entity = parseMimeEntity(original);
+            const subject = entity.headers["subject"];
+            const calendarText = extractCalendarText(entity);
+            const calendar = calendarText !== undefined ? { calendar: calendarText } : {};
+            if (inner.result.state !== "unprotected") {
+                // The stored message's own Subject is the placeholder: the original's stands in when the inner result has none.
+                const fallbackSubject = inner.result.subject === undefined && subject !== undefined ? { subject: decodeHeaderText(subject) } : {};
+                return { ...inner, result: { ...inner.result, ...fallbackSubject, ...calendar, zeroAccess: true } };
+            }
+            return {
+                result: {
+                    state: "protected_at_rest",
+                    zeroAccess: true,
+                    ...calendar,
+                    ...renderDisplayBody(extractDisplayBody(entity)),
+                    ...(subject !== undefined ? { subject: decodeHeaderText(subject) } : {}),
+                    attachments: extractAttachments(entity),
+                },
+                kind: "other",
+            };
+        }
+    }
+
     if (isEncryptedContentType(contentType)) {
         // The active key first, then the retained older ones (see `keySession.ts`'s `retainedEncryptionKeys`), so mail
         // encrypted to a key since replaced still opens. Only ever used to decrypt here - never to encrypt or sign.
@@ -496,6 +648,122 @@ async function evaluateLive(
     return { result: { state: "unprotected" }, kind: "other" };
 }
 
+/** Which OpenPGP form a received message is, if any: RFC 3156 PGP/MIME (`multipart/signed` or `multipart/encrypted` with an OpenPGP
+ * `protocol`), or an inline message - a `text/plain` body that is one armored `PGP MESSAGE`, or a cleartext signature. */
+type PgpKind = "signed" | "encrypted" | "inline-encrypted" | "inline-signed";
+
+const INLINE_PGP_MESSAGE = /^-----BEGIN PGP MESSAGE-----\r?\n[\s\S]*-----END PGP MESSAGE-----$/;
+const INLINE_PGP_SIGNED = /^-----BEGIN PGP SIGNED MESSAGE-----\r?\n[\s\S]*-----END PGP SIGNATURE-----$/;
+
+function pgpKind(contentType: { value: string; params: Record<string, string> }, entity: MimeEntity): PgpKind | undefined {
+    const protocol = contentType.params["protocol"]?.toLowerCase();
+    if (contentType.value === "multipart/signed" && protocol === "application/pgp-signature") {
+        return "signed";
+    }
+    if (contentType.value === "multipart/encrypted" && protocol === "application/pgp-encrypted") {
+        return "encrypted";
+    }
+    if (contentType.value !== "text/plain") {
+        return undefined;
+    }
+    const text = decodeBodyText(entity).trim();
+    return INLINE_PGP_MESSAGE.test(text) ? "inline-encrypted" : INLINE_PGP_SIGNED.test(text) ? "inline-signed" : undefined;
+}
+
+/**
+ * `evaluateLive()` for an OpenPGP message (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*), with the same
+ * trust rules as S/MIME: a signature by a key pinned for the sender (`SignerPins.openPgpKeys`) or the reader's own is verified;
+ * one by a key only attached to the message is `*_unverified_signer` - or `signer_key_changed` when the sender has a different key
+ * pinned; and the key must name the sender, with the protected headers matching the outer ones (`checkIdentityAndHeaders()`).
+ * A signature nobody's key can check is reported through `signerKeyUnknown`, never as failed. The crypto is `pgpMessage.ts`'s,
+ * loaded only here.
+ */
+async function evaluatePgp(
+    kind: PgpKind,
+    rawContentType: string,
+    outer: MimeEntity,
+    unlocked: MessageSecurityKeys | undefined,
+    pins: SignerPinsInput,
+    readerAddress: string | undefined,
+): Promise<LiveEvaluation> {
+    const pgp = await import("./pgpMessage.js");
+    const pinned = (await pgp.readKeysBase64(pinnedOpenPgpKeys(pins))).map((key) => ({ key, trusted: true }));
+    const ownKeys = unlocked?.openPgpKeys ?? [];
+    const candidates: PgpSignerCandidate[] = [...pinned, ...ownKeys.map(({ privateKey }) => ({ key: privateKey.toPublic(), trusted: true }))];
+    const decryptionKeys = ownKeys.map(({ privateKey }) => privateKey);
+    const encrypted = kind === "encrypted" || kind === "inline-encrypted";
+    const text = decodeBodyText(outer).trim();
+    let parsed: ParsedPgpMessage;
+    if (kind === "signed") {
+        parsed = await pgp.parsePgpSignedMessage(rawContentType, outer.body, candidates);
+    } else if (kind === "encrypted") {
+        parsed = await pgp.parsePgpEncryptedMessage(rawContentType, outer.body, decryptionKeys, candidates);
+    } else if (kind === "inline-encrypted") {
+        parsed = await pgp.parsePgpInlineEncrypted(text, decryptionKeys, candidates);
+    } else {
+        parsed = await pgp.parsePgpCleartextSigned(text, candidates);
+    }
+    const resultKind: LiveEvaluation["kind"] = encrypted ? "encrypted" : "signed";
+    if (encrypted && !parsed.decrypted) {
+        return { result: { state: "encrypted", decryptError: NO_KEY_ERROR }, kind: resultKind };
+    }
+    if (parsed.entityText === undefined) {
+        return { result: { state: "signature_failed", signatureFailureReason: "invalid_signature" }, kind: resultKind };
+    }
+    const entity = parseMimeEntity(parsed.entityText);
+    const inline = kind === "inline-encrypted" || kind === "inline-signed";
+    const protectedHeaders: ProtectedHeaders | undefined = inline ? undefined : headersToProtectedHeaders(entity.headers);
+    const hasProtected = !!protectedHeaders && extractAddresses(protectedHeaders.from).length > 0;
+    const hpOuter = encrypted && !inline ? extractHpOuterHeaders(entity.fields) : undefined;
+    const outerComparable: ComparableOuterHeaders = { from: outer.headers["from"], to: outer.headers["to"], cc: outer.headers["cc"], date: outer.headers["date"], subject: outer.headers["subject"] };
+    const recipients = [...extractAddresses(protectedHeaders?.to), ...extractAddresses(protectedHeaders?.cc)];
+    const content: Partial<MessageSecurityResult> = {
+        ...renderDisplayBody(extractDisplayBody(entity)),
+        subject: (hasProtected ? protectedHeaders?.subject : undefined) || undefined,
+        attachments: extractAttachments(entity),
+        ...(hpOuter ? { headerTamperDetected: !outerHeadersMatch(hpOuter, outerComparable) } : {}),
+        ...(readerAddress && recipients.length > 0 ? { notAddressedToReader: !recipients.includes(readerAddress.trim().toLowerCase()) } : {}),
+    };
+    const signature = parsed.signature;
+    if (!signature) {
+        // Encrypted without a signature (an unsigned signed-only message can't happen: it is the signature).
+        return { result: { state: "encrypted", ...content }, kind: resultKind };
+    }
+    if (signature.status === "unknown_key") {
+        return { result: encrypted ? { state: "encrypted", ...content, signerKeyUnknown: true } : { state: "unprotected", signerKeyUnknown: true }, kind: resultKind };
+    }
+    if (signature.status === "invalid") {
+        return { result: { state: "signature_failed", signatureFailureReason: "invalid_signature", ...(encrypted ? content : {}) }, kind: resultKind };
+    }
+    const signer = { signerFingerprint: signature.fingerprint, signerEmails: signature.emails, signerKeyType: "openpgp" as const };
+    const acceptedSigner = { ...signer, signerCertificate: toBase64(signature.candidate.key.write()) };
+    const signedHeaders: Partial<MessageSecurityResult> = hasProtected
+        ? { protectedHeaders: { from: protectedHeaders.from, to: protectedHeaders.to, ...(protectedHeaders.cc !== undefined ? { cc: protectedHeaders.cc } : {}), subject: protectedHeaders.subject } }
+        : {};
+    const failure = checkIdentityAndHeaders(
+        {
+            protectedHeaders: hasProtected ? protectedHeaders : undefined,
+            outerHeaders: outer.headers,
+            outerFields: outer.fields,
+            protectedFields: hasProtected ? entity.fields : undefined,
+            compareSubject: !encrypted,
+        },
+        signature.emails,
+    );
+    // Signed by a key only attached to the message while the sender has OpenPGP keys pinned: they appear to use a new key.
+    const keyChanged = !failure && !signature.candidate.trusted && pinned.length > 0;
+    if (failure || keyChanged) {
+        const reason: SignatureFailureReason = failure ?? "signer_key_changed";
+        return {
+            result: { state: "signature_failed", signatureFailureReason: reason, ...(encrypted ? content : {}), ...(reason === "signer_key_changed" ? acceptedSigner : signer) },
+            kind: resultKind,
+            ...(reason === "signer_key_changed" ? { signedContent: { ...content, ...signedHeaders } } : {}),
+        };
+    }
+    const state: MessageSecurityState = signature.candidate.trusted ? (encrypted ? "encrypted_verified" : "signed_verified") : encrypted ? "encrypted_unverified_signer" : "signed_unverified_signer";
+    return { result: { state, ...content, ...signedHeaders, ...acceptedSigner }, kind: resultKind };
+}
+
 /** Options for `evaluateMessageSecurityWithSeal()`. */
 export interface VerificationSealOptions {
     mailboxUid: string;
@@ -562,7 +830,7 @@ function failedOnlyOnKeyStatus(result: MessageSecurityResult): boolean {
 export async function evaluateMessageSecurityWithSeal(
     rawMime: string,
     unlocked: (MessageSecurityKeys & SealKeyMaterial) | undefined,
-    pinnedSignerFingerprints: string | string[] | undefined,
+    pinnedSignerFingerprints: SignerPinsInput,
     readerAddress: string | undefined,
     options: VerificationSealOptions,
 ): Promise<MessageSecurityResult> {

package/lib/crypto/mime.ts

@@ -541,6 +541,32 @@ export function extractAttachments(entity: MimeEntity, depth = 0): MimeAttachmen
     ];
 }
 
+/**
+ * The text of the first calendar file in `entity` (descending into multipart children, bounded depth): a `text/calendar` or
+ * `application/ics` leaf, whether a body alternative (as Outlook sends an invitation) or an attached `.ics`. `undefined` when there is none.
+ */
+export function extractCalendarText(entity: MimeEntity, depth = 0): string | undefined {
+    const contentType = parseParameterizedHeader(entity.headers["content-type"] ?? "text/plain");
+    if (contentType.value.startsWith("multipart/")) {
+        const boundary = contentType.params["boundary"];
+        if (!boundary || depth >= MAX_MULTIPART_DEPTH) {
+            return undefined;
+        }
+        for (const part of splitMultipart(entity.body, boundary)) {
+            const found = extractCalendarText(parseMimeEntity(part), depth + 1);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    if (contentType.value !== "text/calendar" && contentType.value !== "application/ics") {
+        return undefined;
+    }
+    const bytes = decodeBodyBytes(entity);
+    return bytes ? new TextDecoder().decode(bytes) : undefined;
+}
+
 /** HTML-escapes plain text and wraps it in a whitespace-preserving `<pre>`, so a `text/plain` body can be
  * rendered through the same HTML path without ever being interpreted as markup. */
 export function plainTextToHtml(text: string): string {

package/lib/crypto/openPgpKey.ts

@@ -0,0 +1,118 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The mailbox's own OpenPGP key (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*): generated here, its secret
+ * key sealed under the master key like every other private key, its certificate enrolled with restapi - which publishes it on the
+ * RapidMX discovery endpoint, the Web Key Directory and in an `Autocrypt` header, so OpenPGP users (Proton Mail and others) can
+ * encrypt to the mailbox. S/MIME stays the mailbox's own format; this key is for correspondents who can't receive S/MIME.
+ */
+import type { ApiClient } from "../util/api.js";
+import { type KeyVault, OPENPGP_KEY_TYPE, enrollKey, getEncryptionPolicy, getKeyVault, isOpenPgpKey, recordKeyExport } from "./keyvaultApi.js";
+import { addOpenPgpKey, getUnlockedKeys, OPENPGP_PRIVATE_KEY_AAD_PURPOSE, openMasterKeyWithPassword } from "./keySession.js";
+import type { OpenPgpPrivateKey } from "./openpgp.js";
+import { buildAad, openWithKey, sealWithKey } from "./masterKey.js";
+
+/**
+ * Generates an OpenPGP key for `mailboxAddress` (`openpgp.ts`'s `generateOpenPgpKey()`), seals its secret key under `masterKey`
+ * and enrolls it; restapi makes it the mailbox's active OpenPGP key, superseding any earlier one. Pass the vault's
+ * `masterKeyGeneration` read with `masterKey` as `expectedMasterKeyGeneration` (`409` when another device rotated it meanwhile).
+ * Resolves with the vault and the new key, ready to decrypt and sign with.
+ */
+export async function provisionOpenPgpKey(
+    mailboxUid: string,
+    mailboxAddress: string,
+    masterKey: Uint8Array,
+    expectedMasterKeyGeneration?: number,
+    displayName?: string,
+    client?: ApiClient,
+): Promise<{ vault: KeyVault; key: { fingerprint: string; privateKey: OpenPgpPrivateKey } }> {
+    const { generateOpenPgpKey, readSecretKey } = await import("./openpgp.js");
+    const generated = await generateOpenPgpKey(mailboxAddress, displayName);
+    try {
+        const sealed = await sealWithKey(masterKey, generated.secretKey, buildAad(mailboxUid, OPENPGP_PRIVATE_KEY_AAD_PURPOSE));
+        const vault = await enrollKey(
+            mailboxUid,
+            {
+                useType: "encrypt",
+                type: OPENPGP_KEY_TYPE,
+                publicKey: generated.armoredPublicKey,
+                wrappedKey: { ciphertext: sealed.ciphertext, nonce: sealed.nonce, algorithm: "AES-256-GCM" },
+                ...(expectedMasterKeyGeneration !== undefined ? { expectedMasterKeyGeneration } : {}),
+            },
+            client,
+        );
+        return { vault, key: { fingerprint: generated.fingerprint, privateKey: await readSecretKey(generated.secretKey) } };
+    } finally {
+        generated.secretKey.fill(0);
+    }
+}
+
+/** Provisions already in flight, per mailbox - a second caller joins the first. */
+const inFlight = new Map<string, Promise<boolean>>();
+
+/**
+ * Gives an unlocked mailbox an OpenPGP key when it has none - how every mailbox, including one set up before OpenPGP was
+ * supported, gets one on its owner's next unlock. Resolves `true` when it enrolled one, `false` when there was nothing to do:
+ * the mailbox isn't unlocked, the server doesn't allow OpenPGP (`EncryptionPolicy.allowOpenPgp`), the vault isn't set up yet, or it
+ * already holds an OpenPGP key. Only the mailbox's owner may call this (restapi refuses anybody else's enrollment).
+ */
+export function ensureOpenPgpKey(mailboxUid: string, mailboxAddress: string, displayName?: string, client?: ApiClient): Promise<boolean> {
+    const pending = inFlight.get(mailboxUid);
+    if (pending) {
+        return pending;
+    }
+    const run = (async (): Promise<boolean> => {
+        const unlocked = getUnlockedKeys(mailboxUid);
+        if (!unlocked || unlocked.shared || unlocked.openPgpKeys?.length) {
+            return false;
+        }
+        const policy = await getEncryptionPolicy(client);
+        if (policy.allowOpenPgp !== true) {
+            return false;
+        }
+        const vault = await getKeyVault(mailboxUid, client);
+        if (vault.wrappedKeys.length === 0 || vault.wrappedKeys.some((k) => isOpenPgpKey(k))) {
+            return false;
+        }
+        const { key } = await provisionOpenPgpKey(mailboxUid, mailboxAddress, unlocked.masterKey, vault.masterKeyGeneration, displayName, client);
+        addOpenPgpKey(mailboxUid, unlocked, key);
+        return true;
+    })().finally(() => inFlight.delete(mailboxUid));
+    inFlight.set(mailboxUid, run);
+    return run;
+}
+
+/**
+ * The mailbox's active OpenPGP secret key, armored and protected with `passphrase` - for a user who reads this mailbox's OpenPGP
+ * mail in another OpenPGP app too (Thunderbird, GnuPG...). Like the PKCS#12 export (`keyExport.ts`) it re-opens the vault with
+ * the master password, whatever the session, never touches the session's keys, and is recorded with restapi (kind `encrypt`).
+ * Throws when the mailbox has no OpenPGP key.
+ */
+export async function exportOpenPgpSecretKey(
+    mailboxUid: string,
+    masterPassword: string,
+    passphrase: string,
+    client?: ApiClient,
+): Promise<{ armored: string; fingerprint: string }> {
+    const { readSecretKey, exportProtectedSecretKey } = await import("./openpgp.js");
+    const { vault, masterKey } = await openMasterKeyWithPassword(mailboxUid, masterPassword, client);
+    try {
+        // The newest OpenPGP key enrolled is the active one (restapi appends, and supersedes the earlier ones).
+        const wrapped = [...vault.wrappedKeys].reverse().find((k) => isOpenPgpKey(k));
+        if (!wrapped) {
+            throw new Error("This mailbox has no OpenPGP key to export.");
+        }
+        const raw = await openWithKey(masterKey, wrapped, buildAad(mailboxUid, OPENPGP_PRIVATE_KEY_AAD_PURPOSE));
+        try {
+            const armored = await exportProtectedSecretKey(await readSecretKey(raw), passphrase);
+            await recordKeyExport(mailboxUid, [{ kind: "encrypt", fingerprint: wrapped.fingerprint }], client);
+            return { armored, fingerprint: wrapped.fingerprint };
+        } finally {
+            raw.fill(0);
+        }
+    } finally {
+        masterKey.fill(0);
+    }
+}