@rapidmx/web-client 0.35.0 → 0.37.0

package/dist/lib/crypto/meetingKeys.js

@@ -0,0 +1,87 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The temporary per-meeting key of a meeting with external guests (meet-plugin `specs/meeting_privacy.md` §3-4): a P-256 keypair made
+ * in the browser of whoever creates the meeting, with a self-signed certificate so the CMS code in `smime.ts` seals to it and opens with
+ * it unchanged. Every participant receives the private key in their link's `#k=` part; the organizer also keeps it sealed to their own
+ * zero-access certificate. A live AES-256-GCM key derived from it encrypts the meeting's signaling and relayed media. Shared by the
+ * organizer's calendar editor, meet-plugin and booking-plugin.
+ *
+ * Nothing here talks to the server: the private key never leaves the browser except inside a link or a CMS wrap.
+ */
+import { fromBase64Url, toBase64Url } from "./encoding.js";
+/** The `#` parameter of a link that carries a meeting key. */
+export const MEETING_KEY_FRAGMENT_PARAM = "k";
+/** HKDF `info` of the live key (`specs/meeting_privacy.md` §3). */
+const LIVE_KEY_INFO = "rapidmx-meeting-live-v1";
+const EC_PARAMS = { name: "ECDH", namedCurve: "P-256" };
+async function loadX509() {
+    await import("reflect-metadata");
+    const x509 = await import("@peculiar/x509");
+    x509.cryptoProvider.set(crypto);
+    return x509;
+}
+async function sha256Hex(bytes) {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** A new meeting key valid until `expiresAt` (its certificate's `notAfter`). */
+export async function generateMeetingKey(expiresAt) {
+    const x509 = await loadX509();
+    // ECDSA to self-sign the certificate; the same P-256 key is re-imported as ECDH to open what is sealed to it (`importMeetingKey()`).
+    const keys = (await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]));
+    const cert = await x509.X509CertificateGenerator.createSelfSigned({
+        serialNumber: toHex(crypto.getRandomValues(new Uint8Array(16))),
+        name: "CN=meeting",
+        notBefore: new Date(Date.now() - 60000),
+        notAfter: expiresAt,
+        signingAlgorithm: { name: "ECDSA", hash: "SHA-256" },
+        keys,
+    });
+    const certificateDer = new Uint8Array(cert.rawData);
+    const pkcs8 = new Uint8Array(await crypto.subtle.exportKey("pkcs8", keys.privateKey));
+    return { pkcs8, certificateDer, fingerprint: await sha256Hex(certificateDer) };
+}
+function toHex(bytes) {
+    // A positive serial: the top bit clear.
+    const copy = Uint8Array.from(bytes);
+    copy[0] &= 0x7f;
+    return Array.from(copy, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** The `#` part a guest's link carries for `pkcs8`: `k=<base64url>`. */
+export function meetingKeyFragment(pkcs8) {
+    return `${MEETING_KEY_FRAGMENT_PARAM}=${toBase64Url(pkcs8)}`;
+}
+/** The meeting key in `hash` (a `location.hash`, with or without its `#`), or `undefined` when it carries none or it is malformed. */
+export function readMeetingKeyFragment(hash) {
+    const params = new URLSearchParams(hash.replace(/^#/, ""));
+    const value = params.get(MEETING_KEY_FRAGMENT_PARAM);
+    if (!value || !/^[A-Za-z0-9_-]{16,1024}$/.test(value)) {
+        return undefined;
+    }
+    try {
+        return fromBase64Url(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The meeting key `pkcs8` as the CMS code opens with it, and its live key for meeting `meetingUid`. Rejects a key that isn't P-256. */
+export async function importMeetingKey(pkcs8, certificateDer, meetingUid) {
+    // Extractable once, only to read its scalar for the live key; the key kept for CMS isn't.
+    const readable = await crypto.subtle.importKey("pkcs8", pkcs8, EC_PARAMS, true, ["deriveBits"]);
+    const jwk = await crypto.subtle.exportKey("jwk", readable);
+    /* v8 ignore next 3 -- an imported PKCS#8 private key always exports its scalar */
+    if (!jwk.d) {
+        throw new Error("This is not a meeting key.");
+    }
+    const privateKey = await crypto.subtle.importKey("pkcs8", pkcs8, EC_PARAMS, false, ["deriveBits"]);
+    return { decryptionKey: { certDer: certificateDer, privateKey }, liveKey: await deriveLiveKey(fromBase64Url(jwk.d), meetingUid) };
+}
+/** The AES-256-GCM live key of meeting `meetingUid` from `ikm`, the meeting key's private scalar. Non-extractable. */
+export async function deriveLiveKey(ikm, meetingUid) {
+    const base = await crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new TextEncoder().encode(meetingUid), info: new TextEncoder().encode(LIVE_KEY_INFO) }, base, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}

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

@@ -34,7 +34,9 @@
  * accepted or automatic rotation still verifies.
  */
 import { MimeAttachment, MimeHeaderField } from "./mime.js";
+import { type DecryptionKey } from "./smime.js";
 import { ProtectedHeaders } from "./smimeMessage.js";
+import type { OpenPgpPrivateKey } from "./openpgp.js";
 import { type PublicKey } from "./keyvaultApi.js";
 import { type SealKeyMaterial, type SealedVerificationState } from "./verificationSeal.js";
 export { signingKeyFingerprints } from "./keyvaultApi.js";
@@ -49,7 +51,7 @@ export { signingKeyFingerprints } from "./keyvaultApi.js";
  * `sealedState`, `signerFingerprint`, the recovered content, `liveState`/`liveSignatureFailureReason`, and
  * `laterCompromised` when the signer key has since been revoked as compromised. A UI should show it as "verified when
  * first opened" - distinct from the live verified states, and with a warning when `laterCompromised` is set. */
-export type MessageSecurityState = "encrypted" | "signed_verified" | "encrypted_verified" | "signed_unverified_signer" | "encrypted_unverified_signer" | "signature_failed" | "verified_at_first_open" | "unprotected";
+export type MessageSecurityState = "encrypted" | "signed_verified" | "encrypted_verified" | "signed_unverified_signer" | "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
  * doesn't verify over the content (or a `multipart/signed` body doesn't hold exactly two parts).
  * `signer_key_changed`: pinned fingerprints were supplied and the signer certificate matches none of them, but it
@@ -92,6 +94,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
@@ -118,6 +127,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
@@ -190,7 +207,7 @@ export declare function checkSignerBinding(input: SignerBindingInput): Promise<S
  * An encrypted message is decrypted with `unlocked`'s active encryption key or any of its `retainedEncryptionKeys` (the
  * older keys a rotation replaced - see `keySession.ts`), matched by recipient identifier first.
  */
-export declare function evaluateMessageSecurity(rawMime: string, unlocked: MessageSecurityKeys | undefined, pinnedSignerFingerprints?: string | string[], readerAddress?: string): Promise<MessageSecurityResult>;
+export declare function evaluateMessageSecurity(rawMime: string, unlocked: MessageSecurityKeys | undefined, pinnedSignerFingerprints?: SignerPinsInput, readerAddress?: string): Promise<MessageSecurityResult>;
 /** The keys `evaluateMessageSecurity()` reads from an unlocked session (`keySession.ts`'s `UnlockedKeys`). */
 export interface MessageSecurityKeys {
     encryptionPrivateKey?: CryptoKey;
@@ -200,7 +217,43 @@ export interface MessageSecurityKeys {
         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 declare function openZeroAccessSummary(sealedSummary: string, keys: DecryptionKey[] | undefined): Promise<{
+    subject: string;
+    preview: string;
+} | 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 declare function openZeroAccessMessage(rawMime: string, unlocked: MessageSecurityKeys | undefined): Promise<string | undefined>;
 /** Options for `evaluateMessageSecurityWithSeal()`. */
 export interface VerificationSealOptions {
     mailboxUid: string;
@@ -248,4 +301,4 @@ export interface VerificationSealOptions {
  * `unlocked` was destroyed (`keySession.ts`), before evaluating anything, or if it is destroyed while sealing; otherwise
  * never throws - a seal that can't be built (e.g. uids too long for the size limit) just leaves `sealToWrite` unset.
  */
-export declare function evaluateMessageSecurityWithSeal(rawMime: string, unlocked: (MessageSecurityKeys & SealKeyMaterial) | undefined, pinnedSignerFingerprints: string | string[] | undefined, readerAddress: string | undefined, options: VerificationSealOptions): Promise<MessageSecurityResult>;
+export declare function evaluateMessageSecurityWithSeal(rawMime: string, unlocked: (MessageSecurityKeys & SealKeyMaterial) | undefined, pinnedSignerFingerprints: SignerPinsInput, readerAddress: string | undefined, options: VerificationSealOptions): Promise<MessageSecurityResult>;

package/dist/lib/crypto/messageSecurity.js

@@ -37,10 +37,10 @@
  * `untrusted_signer`. Previously pinned keys count as pins (see `signingKeyFingerprints()`), so mail signed before an
  * accepted or automatic rotation still verifies.
  */
-import { decodeHeaderText, extractAddresses, parseMimeEntity, parseParameterizedHeader, plainTextToHtml } from "./mime.js";
-import { toBase64 } from "./encoding.js";
-import { computeCertFingerprint, extractCertificateEmails } from "./smime.js";
-import { parseEncryptedMessageWithKeys, parseSignedOnlyMessage } from "./smimeMessage.js";
+import { bytesToBinaryString, decodeBodyText, decodeBase64Text, decodeHeaderText, extractAddresses, extractAttachments, extractCalendarText, extractDisplayBody, parseMimeEntity, parseParameterizedHeader, plainTextToHtml, } from "./mime.js";
+import { fromBase64, toBase64 } from "./encoding.js";
+import { computeCertFingerprint, decryptEnvelopedDataWithKeys, extractCertificateEmails } from "./smime.js";
+import { extractHpOuterHeaders, headersToProtectedHeaders, outerHeadersMatch, parseEncryptedMessageWithKeys, parseSignedOnlyMessage, } from "./smimeMessage.js";
 import { isTrustedForVerification } from "./keyvaultApi.js";
 import { KeysLockedError } from "./masterKey.js";
 import { buildVerificationSeal, openVerificationSeal, rawMimeSha256 } from "./verificationSeal.js";
@@ -103,7 +103,11 @@ function sameInstant(signed, outer) {
     return Number.isNaN(left) || left === Date.parse(String(outer));
 }
 function normalizePins(pins) {
-    return (Array.isArray(pins) ? pins : pins === undefined ? [] : [pins]).map((pin) => pin.toLowerCase());
+    const list = Array.isArray(pins) ? pins : pins === undefined ? [] : typeof pins === "string" ? [pins] : pins.fingerprints;
+    return list.map((pin) => pin.toLowerCase());
+}
+function pinnedOpenPgpKeys(pins) {
+    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.
  * Returns `undefined` when the signer is accepted, otherwise the failure reason. A pin mismatch is
@@ -120,12 +124,13 @@ export async function checkSignerBinding(input) {
     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, certDer) {
+/** 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, signerEmails) {
     const { protectedHeaders, outerHeaders } = input;
     if (hasRepeatedAddressField(input.outerFields) || hasRepeatedAddressField(input.protectedFields)) {
         return "header_mismatch";
@@ -133,7 +138,7 @@ function checkIdentityAndHeaders(input, certDer) {
     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);
@@ -174,13 +179,66 @@ function checkIdentityAndHeaders(input, certDer) {
 export async function evaluateMessageSecurity(rawMime, unlocked, pinnedSignerFingerprints, readerAddress) {
     return (await evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress)).result;
 }
-async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress) {
-    const { headers, body, fields } = parseMimeEntity(rawMime);
+/**
+ * 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, keys) {
+    if (!keys?.length) {
+        return undefined;
+    }
+    try {
+        const json = JSON.parse(new TextDecoder().decode(await decryptEnvelopedDataWithKeys(fromBase64(sealedSummary), keys)));
+        const { subject, preview } = (json ?? {});
+        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, unlocked) {
+    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, keys) {
+    const der = decodeBase64Text(body);
+    if (!der) {
+        return undefined;
+    }
+    try {
+        return bytesToBinaryString(await decryptEnvelopedDataWithKeys(der, keys));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress, sealedAtRest = false) {
+    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
     // send time, inside the encrypted content) are compared against to detect post-send tampering.
@@ -248,6 +306,34 @@ async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerA
             kind: "signed",
         };
     }
+    // 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.
@@ -290,6 +376,108 @@ async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerA
     }
     return { result: { state: "unprotected" }, kind: "other" };
 }
+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, entity) {
+    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, rawContentType, outer, unlocked, pins, readerAddress) {
+    const pgp = await import("./pgpMessage.js");
+    const pinned = (await pgp.readKeysBase64(pinnedOpenPgpKeys(pins))).map((key) => ({ key, trusted: true }));
+    const ownKeys = unlocked?.openPgpKeys ?? [];
+    const candidates = [...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;
+    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 = 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 = inline ? undefined : headersToProtectedHeaders(entity.headers);
+    const hasProtected = !!protectedHeaders && extractAddresses(protectedHeaders.from).length > 0;
+    const hpOuter = encrypted && !inline ? extractHpOuterHeaders(entity.fields) : undefined;
+    const outerComparable = { 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 = {
+        ...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" };
+    const acceptedSigner = { ...signer, signerCertificate: toBase64(signature.candidate.key.write()) };
+    const signedHeaders = 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 = 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 = signature.candidate.trusted ? (encrypted ? "encrypted_verified" : "signed_verified") : encrypted ? "encrypted_unverified_signer" : "signed_unverified_signer";
+    return { result: { state, ...content, ...signedHeaders, ...acceptedSigner }, kind: resultKind };
+}
 const LIVE_VERIFIED_STATES = ["signed_verified", "encrypted_verified"];
 /** Whether a live result failed only because of the signer key's status - the cases a seal may override. Every other
  * failure (an invalid signature, identity or header mismatch, `untrusted_signer`, HP-Outer tampering) never is. */

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

@@ -135,6 +135,11 @@ export interface MimeAttachment {
  * reported as one attachment, never expanded.
  */
 export declare function extractAttachments(entity: MimeEntity, depth?: number): MimeAttachment[];
+/**
+ * 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 declare function extractCalendarText(entity: MimeEntity, depth?: number): string | 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 declare function plainTextToHtml(text: string): string;

package/dist/lib/crypto/mime.js

@@ -478,6 +478,31 @@ export function extractAttachments(entity, depth = 0) {
         },
     ];
 }
+/**
+ * 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, depth = 0) {
+    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) {

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

@@ -0,0 +1,39 @@
+/**
+ * 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 } from "./keyvaultApi.js";
+import type { OpenPgpPrivateKey } from "./openpgp.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 declare function provisionOpenPgpKey(mailboxUid: string, mailboxAddress: string, masterKey: Uint8Array, expectedMasterKeyGeneration?: number, displayName?: string, client?: ApiClient): Promise<{
+    vault: KeyVault;
+    key: {
+        fingerprint: string;
+        privateKey: OpenPgpPrivateKey;
+    };
+}>;
+/**
+ * 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 declare function ensureOpenPgpKey(mailboxUid: string, mailboxAddress: string, displayName?: string, client?: ApiClient): Promise<boolean>;
+/**
+ * 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 declare function exportOpenPgpSecretKey(mailboxUid: string, masterPassword: string, passphrase: string, client?: ApiClient): Promise<{
+    armored: string;
+    fingerprint: string;
+}>;

package/dist/lib/crypto/openPgpKey.js

@@ -0,0 +1,89 @@
+import { OPENPGP_KEY_TYPE, enrollKey, getEncryptionPolicy, getKeyVault, isOpenPgpKey, recordKeyExport } from "./keyvaultApi.js";
+import { addOpenPgpKey, getUnlockedKeys, OPENPGP_PRIVATE_KEY_AAD_PURPOSE, openMasterKeyWithPassword } from "./keySession.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, mailboxAddress, masterKey, expectedMasterKeyGeneration, displayName, client) {
+    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();
+/**
+ * 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, mailboxAddress, displayName, client) {
+    const pending = inFlight.get(mailboxUid);
+    if (pending) {
+        return pending;
+    }
+    const run = (async () => {
+        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, masterPassword, passphrase, client) {
+    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);
+    }
+}