@rapidmx/web-client 0.36.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

@@ -36,6 +36,7 @@
 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";
@@ -126,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
@@ -198,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;
@@ -214,7 +223,22 @@ export interface MessageSecurityKeys {
         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
@@ -277,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 { bytesToBinaryString, decodeBase64Text, decodeHeaderText, extractAddresses, extractAttachments, extractCalendarText, extractDisplayBody, parseMimeEntity, parseParameterizedHeader, plainTextToHtml, } from "./mime.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 { parseEncryptedMessageWithKeys, parseSignedOnlyMessage } from "./smimeMessage.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);
@@ -223,12 +228,17 @@ async function openZeroAccess(body, keys) {
     }
 }
 async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress, sealedAtRest = false) {
-    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
     // send time, inside the encrypted content) are compared against to detect post-send tampering.
@@ -366,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/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);
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * OpenPGP keys (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*): the mailbox's own key, generated here, and the
+ * keys of correspondents who use OpenPGP (Proton Mail, Thunderbird, GnuPG). Built on OpenPGP.js - which runs on WebCrypto and audited
+ * curve code, never OpenSSL - and loaded only when OpenPGP is used: this module is only ever imported dynamically.
+ *
+ * S/MIME stays RapidMX's own format; an OpenPGP key exists so OpenPGP users can reach RapidMX users, and RapidMX users them.
+ */
+import * as openpgp from "openpgp";
+export type OpenPgpPrivateKey = openpgp.PrivateKey;
+export type OpenPgpPublicKey = openpgp.PublicKey;
+/** A freshly generated key: the public certificate to publish and the secret key to seal under the master key. */
+export interface GeneratedOpenPgpKey {
+    /** Base64 of the binary transferable public key (`PublicKey.publicKey`). */
+    publicKey: string;
+    /** The same certificate, ASCII armored (what enrollment sends and the user can export). */
+    armoredPublicKey: string;
+    /** The binary transferable secret key, unencrypted - the caller seals it under the master key and zeroes this copy. */
+    secretKey: Uint8Array;
+    /** The primary key's fingerprint (40 hex characters for a v4 key, 64 for v6). */
+    fingerprint: string;
+}
+/** Which OpenPGP key version to generate: 4 (RFC 4880, the default - what every OpenPGP app reads, GnuPG included) or 6 (RFC 9580). */
+export type OpenPgpKeyVersion = 4 | 6;
+/**
+ * Generates the mailbox's OpenPGP key: an Ed25519 primary key with a Curve25519 encryption subkey and one user ID,
+ * `displayName <address>`, never expiring (rotation replaces it). A v4 key uses the long-established EdDSA/ECDH Curve25519
+ * algorithms; a v6 key RFC 9580's Ed25519/X25519. It carries no passphrase: like every other private key, its secret half is
+ * sealed under the master key before it leaves this device.
+ */
+export declare function generateOpenPgpKey(address: string, displayName?: string, version?: OpenPgpKeyVersion): Promise<GeneratedOpenPgpKey>;
+/** A rotation's new key with its user ID certified by the key it replaces, so correspondents who pinned the old one accept the
+ * new one without asking (restapi `OpenPgpKeyUtils.canReplaceOpenPgpKeyAutomatically()`). */
+export declare function certifyWithPredecessor(successor: GeneratedOpenPgpKey, predecessor: OpenPgpPrivateKey): Promise<GeneratedOpenPgpKey>;
+/** The secret key in `bytes` (a sealed `WrappedPrivateKey`'s plaintext), ready to decrypt and sign with. */
+export declare function readSecretKey(bytes: Uint8Array): Promise<OpenPgpPrivateKey>;
+/** The certificate in `base64` (`PublicKey.publicKey`), or `undefined` when it isn't one. */
+export declare function readPublicKey(base64: string): Promise<OpenPgpPublicKey | undefined>;
+/** Every certificate in an armored or binary key block (e.g. an attached `application/pgp-keys` part, or a pasted one). */
+export declare function readPublicKeys(block: string | Uint8Array): Promise<OpenPgpPublicKey[]>;
+/** The email addresses a certificate's user IDs name with a verifying self-signature, lowercased. */
+export declare function keyEmails(key: OpenPgpPublicKey): Promise<string[]>;
+/** A certificate's armored form, for export or for attaching to a message. */
+export declare function armorPublicKey(key: OpenPgpPublicKey): string;
+/** A secret key armored and protected with `passphrase` - the export a user imports into another OpenPGP app. */
+export declare function exportProtectedSecretKey(key: OpenPgpPrivateKey, passphrase: string): Promise<string>;
+/** `key`'s public certificate as base64 (`PublicKey.publicKey`). */
+export declare function publicKeyBase64(key: OpenPgpPrivateKey | OpenPgpPublicKey): string;

package/dist/lib/crypto/openpgp.js

@@ -0,0 +1,88 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * OpenPGP keys (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*): the mailbox's own key, generated here, and the
+ * keys of correspondents who use OpenPGP (Proton Mail, Thunderbird, GnuPG). Built on OpenPGP.js - which runs on WebCrypto and audited
+ * curve code, never OpenSSL - and loaded only when OpenPGP is used: this module is only ever imported dynamically.
+ *
+ * S/MIME stays RapidMX's own format; an OpenPGP key exists so OpenPGP users can reach RapidMX users, and RapidMX users them.
+ */
+import * as openpgp from "openpgp";
+import { fromBase64, toBase64 } from "./encoding.js";
+/**
+ * Generates the mailbox's OpenPGP key: an Ed25519 primary key with a Curve25519 encryption subkey and one user ID,
+ * `displayName <address>`, never expiring (rotation replaces it). A v4 key uses the long-established EdDSA/ECDH Curve25519
+ * algorithms; a v6 key RFC 9580's Ed25519/X25519. It carries no passphrase: like every other private key, its secret half is
+ * sealed under the master key before it leaves this device.
+ */
+export async function generateOpenPgpKey(address, displayName, version = 4) {
+    const userIDs = [{ ...(displayName ? { name: displayName } : {}), email: address }];
+    const { privateKey, publicKey } = version === 6
+        ? await openpgp.generateKey({ type: "curve25519", userIDs, format: "object", config: { v6Keys: true } })
+        : await openpgp.generateKey({ type: "ecc", curve: "curve25519Legacy", userIDs, format: "object" });
+    return {
+        publicKey: toBase64(publicKey.write()),
+        armoredPublicKey: publicKey.armor(),
+        secretKey: privateKey.write(),
+        fingerprint: publicKey.getFingerprint(),
+    };
+}
+/** A rotation's new key with its user ID certified by the key it replaces, so correspondents who pinned the old one accept the
+ * new one without asking (restapi `OpenPgpKeyUtils.canReplaceOpenPgpKeyAutomatically()`). */
+export async function certifyWithPredecessor(successor, predecessor) {
+    const secret = await openpgp.readPrivateKey({ binaryKey: successor.secretKey });
+    const certified = await secret.signPrimaryUser([predecessor]);
+    const publicKey = certified.toPublic();
+    return { ...successor, publicKey: toBase64(publicKey.write()), armoredPublicKey: publicKey.armor(), secretKey: certified.write() };
+}
+/** The secret key in `bytes` (a sealed `WrappedPrivateKey`'s plaintext), ready to decrypt and sign with. */
+export async function readSecretKey(bytes) {
+    return await openpgp.readPrivateKey({ binaryKey: bytes });
+}
+/** The certificate in `base64` (`PublicKey.publicKey`), or `undefined` when it isn't one. */
+export async function readPublicKey(base64) {
+    try {
+        return await openpgp.readKey({ binaryKey: fromBase64(base64) });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every certificate in an armored or binary key block (e.g. an attached `application/pgp-keys` part, or a pasted one). */
+export async function readPublicKeys(block) {
+    try {
+        const keys = typeof block === "string" && block.includes("-----BEGIN PGP PUBLIC KEY BLOCK-----")
+            ? await openpgp.readKeys({ armoredKeys: block })
+            : await openpgp.readKeys({ binaryKeys: typeof block === "string" ? fromBase64(block.replace(/\s+/g, "")) : block });
+        return keys.filter((key) => !key.isPrivate());
+    }
+    catch {
+        return [];
+    }
+}
+/** The email addresses a certificate's user IDs name with a verifying self-signature, lowercased. */
+export async function keyEmails(key) {
+    const emails = [];
+    for (const user of key.users) {
+        const email = user.userID?.email;
+        if (email && (await user.verify().then(() => true, () => false))) {
+            emails.push(email.toLowerCase());
+        }
+    }
+    return emails;
+}
+/** A certificate's armored form, for export or for attaching to a message. */
+export function armorPublicKey(key) {
+    return key.armor();
+}
+/** A secret key armored and protected with `passphrase` - the export a user imports into another OpenPGP app. */
+export async function exportProtectedSecretKey(key, passphrase) {
+    const copy = await openpgp.readPrivateKey({ binaryKey: key.write() });
+    return (await openpgp.encryptKey({ privateKey: copy, passphrase })).armor();
+}
+/** `key`'s public certificate as base64 (`PublicKey.publicKey`). */
+export function publicKeyBase64(key) {
+    return toBase64(key.toPublic().write());
+}