@rapidmx/web-client 0.36.0 → 0.37.0

package/lib/crypto/keyvaultApi.ts

@@ -15,9 +15,10 @@ import { ApiClient, ApiRequestError, withClient } from "../util/api.js";
 /** A cryptographic public key used to sign or encrypt messages — safe to expose publicly. Mirrors
  * `@rapidmx/restapi`'s `PublicKey` type exactly. */
 export interface PublicKey {
-    /** Base64-encoded DER X.509 certificate. */
+    /** Base64-encoded DER X.509 certificate - or, for `type: "openpgp"`, the binary OpenPGP transferable public key. */
     publicKey: string;
-    /** The key's type/format (e.g. `x509`). */
+    /** The key's type/format: `x509` (S/MIME), or `openpgp` - an OpenPGP certificate, which both encrypts and signs and is listed
+     * once, with `useType: "encrypt"` (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*). */
     type: string;
     useType: "sign" | "encrypt";
     /** SHA-256 fingerprint of the certificate, hex encoded. */
@@ -48,6 +49,23 @@ export interface WrappedPrivateKey {
     algorithm: string;
     fingerprint: string;
     useType: KeyUseType;
+    /** `"openpgp"` for an OpenPGP secret key (sealed with `OPENPGP_PRIVATE_KEY_AAD_PURPOSE`); absent for a PKCS#8 key. */
+    type?: string;
+}
+
+/** `PublicKey.type` of an OpenPGP certificate. */
+export const OPENPGP_KEY_TYPE = "openpgp";
+
+/** Whether `key` is an OpenPGP certificate (or an OpenPGP secret key's wrap). */
+export function isOpenPgpKey(key: { type?: string } | undefined): boolean {
+    return key?.type === OPENPGP_KEY_TYPE;
+}
+
+/** A key's format: `"openpgp"`, or `"x509"` for every other key (S/MIME). */
+export type KeyFormat = "x509" | "openpgp";
+
+export function keyFormat(key: { type?: string }): KeyFormat {
+    return isOpenPgpKey(key) ? "openpgp" : "x509";
 }
 
 /** What a mailbox's own key is used for. `sign`/`encrypt` keys are published (`Mailbox.keys`); `zero-access` keys never are.
@@ -83,8 +101,14 @@ export interface MasterKeyWrap {
 export interface EncryptionPreference {
     lastSeen?: number;
     preferEncrypt: "mutual" | "nopreference";
+    /** Which end-to-end format the address would rather receive when a sender can use either (restapi
+     * `specs/end-to-end_encryption.md` *Choosing the format*). Absent: no preference. */
+    preferFormat?: EndToEndFormat;
 }
 
+/** The two end-to-end encryption formats. */
+export type EndToEndFormat = "smime" | "openpgp";
+
 /** A newly observed key that differs from a contact's pinned key of the same `useType` - restapi records it instead of
  * silently replacing the pin (the spec's Key Conflict Handling) until the user resolves it with `resolveKeyConflict()`.
  * A contact holds at most one per `useType`. Mirrors `@rapidmx/restapi`'s `KeyConflict`. */
@@ -152,10 +176,10 @@ export function getKeyVault(mailboxUid: string, client?: ApiClient): Promise<Key
  * `revocationReason` - a superseded key may still verify old mail (`isTrustedForVerification()`) but is never used for
  * new mail. Shared by `crypto/keySession.ts` (the
  * mailbox's own keys) and `crypto/composeSecurity.ts` (a recipient's discovered keys). */
-export function findActivePublicKey(keys: PublicKey[], useType: "sign" | "encrypt"): PublicKey | undefined {
+export function findActivePublicKey(keys: PublicKey[], useType: "sign" | "encrypt", format: KeyFormat = "x509"): PublicKey | undefined {
     const now = Date.now();
     return keys
-        .filter((k) => k.useType === useType && !k.revokedAt && k.notAfter > now)
+        .filter((k) => k.useType === useType && keyFormat(k) === format && !k.revokedAt && k.notAfter > now)
         .sort((a, b) => b.notBefore - a.notBefore)[0];
 }
 
@@ -199,7 +223,11 @@ export interface EnrollKeyInput extends ExpectedMasterKeyGeneration {
     csr?: string;
     /** An already-issued PEM certificate — required (and only meaningful) for `useType: "sign"`. */
     certificate?: string;
-    wrappedKey: Omit<WrappedPrivateKey, "fingerprint" | "useType">;
+    /** `"openpgp"` to enroll the mailbox's OpenPGP key (with `useType: "encrypt"`): self-certified, no CA. */
+    type?: string;
+    /** The OpenPGP public key (armored or base64 binary) - required, and only meaningful, with `type: "openpgp"`. */
+    publicKey?: string;
+    wrappedKey: Omit<WrappedPrivateKey, "fingerprint" | "useType" | "type">;
     /** Only meaningful the very first time a mailbox enrolls a key at all (bootstraps its master key). */
     masterKeyWraps?: MasterKeyWrap[];
 }
@@ -655,6 +683,11 @@ export interface KeyLookupResult {
     keyConflicts?: KeyConflict[];
     /** Keys that were pinned before, newest first - see `PreviousKey`. */
     previousKeys?: PreviousKey[];
+    /** The format to use for a recipient reachable in both (restapi *Choosing the format*): the user's choice for the contact, else what
+     * the address advertises, else what it was last seen using. Absent when nothing says - S/MIME then. */
+    preferredFormat?: EndToEndFormat;
+    /** Where `preferredFormat` came from. */
+    preferredFormatSource?: "contact" | "advertised" | "observed";
 }
 
 /** Server-side Discovery: the server itself performs the `_rapidmx` DNS lookup and remote key-endpoint
@@ -669,8 +702,11 @@ export function lookupKeys(mailboxUid: string, addr: string, client?: ApiClient)
 /** What `trustSigner()` pins: the sender's address and the certificate that signed their message. */
 export interface TrustSignerInput {
     address: string;
-    /** Base64 DER of the signer certificate - `MessageSecurityResult.signerCertificate`. */
+    /** Base64 DER of the signer certificate - `MessageSecurityResult.signerCertificate` - or, with `type: "openpgp"`, an OpenPGP
+     * public key (armored or base64 binary): a signer's, a key attached to a message, or one the user pasted. */
     certificate: string;
+    /** `"openpgp"` to pin an OpenPGP key (it encrypts and signs); omitted for an X.509 signing certificate. */
+    type?: string;
 }
 
 /**
@@ -696,7 +732,7 @@ export async function trustSigner(mailboxUid: string, input: TrustSignerInput, c
     try {
         return await withClient<KeyLookupResult>(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/trust`, {
             method: "POST",
-            body: JSON.stringify({ address: input.address, certificate: input.certificate }),
+            body: JSON.stringify({ address: input.address, certificate: input.certificate, ...(input.type ? { type: input.type } : {}) }),
         });
     } catch (err) {
         if (err instanceof ApiRequestError && err.status === 409) {
@@ -721,6 +757,8 @@ export interface ResolveKeyConflictInput {
     /** For `"accept"`: base64 DER of the certificate to pin (e.g. `MessageSecurityResult.signerCertificate` of a
      * `signer_key_changed` result). Omitted, restapi pins the recorded conflict's `observedKey`. */
     certificate?: string;
+    /** `"openpgp"` for the contact's OpenPGP key (always `useType: "encrypt"`); omitted for its S/MIME certificate. */
+    type?: string;
 }
 
 /** The contact's resulting key state after `resolveKeyConflict()`. */
@@ -755,6 +793,7 @@ export async function resolveKeyConflict(
         action: input.action,
         expectedPinnedFingerprint: input.expectedPinnedFingerprint,
         ...(input.certificate !== undefined ? { certificate: input.certificate } : {}),
+        ...(input.type ? { type: input.type } : {}),
     };
     try {
         return await withClient<ResolveKeyConflictResult>(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/resolve`, {
@@ -779,6 +818,9 @@ export interface EncryptionPolicy {
      * supports zero-access encryption (its stored value or the server default); absent from one that doesn't, which a
      * caller treats as not allowed. */
     allowZeroAccess?: boolean;
+    /** "Allow OpenPGP": whether mailboxes may enroll and publish OpenPGP keys, for mail with OpenPGP users. Absent from a server
+     * that predates it, which a caller treats as not allowed. */
+    allowOpenPgp?: boolean;
 }
 
 /** The system-wide encryption policy (readable by any authenticated user, used to decide what encryption

package/lib/crypto/meetingKeys.ts

@@ -0,0 +1,118 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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";
+import type { DecryptionKey } from "./smime.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: EcKeyImportParams = { name: "ECDH", namedCurve: "P-256" };
+
+/** A meeting key as its creator holds it. */
+export interface GeneratedMeetingKey {
+    /** PKCS#8 DER of the private key - what a link carries and a wrap seals. */
+    pkcs8: Uint8Array;
+    /** The self-signed certificate's DER - what the server stores and data is sealed to. */
+    certificateDer: Uint8Array;
+    /** SHA-256 of `certificateDer`, lowercase hex. */
+    fingerprint: string;
+}
+
+async function loadX509(): Promise<typeof import("@peculiar/x509")> {
+    await import("reflect-metadata");
+    const x509 = await import("@peculiar/x509");
+    x509.cryptoProvider.set(crypto);
+    return x509;
+}
+
+async function sha256Hex(bytes: Uint8Array): Promise<string> {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes as BufferSource));
+    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: Date): Promise<GeneratedMeetingKey> {
+    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() - 60_000),
+        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: Uint8Array): string {
+    // 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: Uint8Array): string {
+    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: string): Uint8Array | undefined {
+    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: Uint8Array,
+    certificateDer: Uint8Array,
+    meetingUid: string,
+): Promise<{ decryptionKey: DecryptionKey; liveKey: CryptoKey }> {
+    // 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 as BufferSource, 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 as BufferSource, 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: Uint8Array, meetingUid: string): Promise<CryptoKey> {
+    const base = await crypto.subtle.importKey("raw", ikm as BufferSource, "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/lib/crypto/messageSecurity.ts

@@ -42,6 +42,8 @@ import {
     MimeAttachment,
     MimeHeaderField,
     bytesToBinaryString,
+    decodeBodyText,
+    type MimeEntity,
     decodeBase64Text,
     decodeHeaderText,
     extractAddresses,
@@ -54,7 +56,17 @@ import {
 } from "./mime.js";
 import { fromBase64, toBase64 } from "./encoding.js";
 import { type DecryptionKey, computeCertFingerprint, decryptEnvelopedDataWithKeys, extractCertificateEmails } from "./smime.js";
-import { ComparableOuterHeaders, ProtectedHeaders, parseEncryptedMessageWithKeys, parseSignedOnlyMessage } from "./smimeMessage.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";
@@ -161,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
@@ -280,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.
@@ -299,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";
@@ -313,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);
@@ -357,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;
@@ -372,8 +398,22 @@ export interface MessageSecurityKeys {
     /** 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
@@ -437,16 +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
@@ -603,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;
@@ -669,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/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);
+    }
+}