@rapidmx/web-client 0.35.0 → 0.37.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());
+}

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

@@ -0,0 +1,51 @@
+import { type OpenPgpPrivateKey, type OpenPgpPublicKey } from "./openpgp.js";
+import { type MimePart, type ProtectedHeaders } from "./smimeMessage.js";
+/**
+ * An RFC 3156 `multipart/encrypted` message: the inner entity (protected headers, the body and - with `attachKey` - our public
+ * key) signed with `signingKey` when given and encrypted to every key in `recipientKeys` in one OpenPGP message. Per the spec's
+ * "Encrypt to Self", `recipientKeys` MUST include the sender's own key.
+ */
+export declare function buildPgpEncryptedMessage(bodyContentType: string, bodyText: string, protectedHeaders: ProtectedHeaders, outerHeaders: ProtectedHeaders, recipientKeys: OpenPgpPublicKey[], signingKey?: OpenPgpPrivateKey, attachKey?: string): Promise<MimePart>;
+/** An RFC 3156 detached `multipart/signed` message: the inner entity (protected headers, the body and - with `attachKey` - our
+ * public key), signed with `signingKey`. */
+export declare function buildPgpSignedOnlyMessage(bodyContentType: string, bodyText: string, protectedHeaders: ProtectedHeaders, signingKey: OpenPgpPrivateKey, attachKey?: string): Promise<MimePart>;
+/** A key that may have made a signature: a pinned one is trusted, one only attached to the message is not. */
+export interface PgpSignerCandidate {
+    key: OpenPgpPublicKey;
+    trusted: boolean;
+}
+/** What a signature proved. `"unknown_key"`: no candidate key has the signing key's ID, so it can't be checked at all. */
+export type PgpSignatureOutcome = {
+    status: "verified";
+    candidate: PgpSignerCandidate;
+    fingerprint: string;
+    emails: string[];
+} | {
+    status: "invalid";
+} | {
+    status: "unknown_key";
+};
+/** A recovered OpenPGP message: the inner entity (a binary string, as `mime.ts` parses it) and what its signature proved. */
+export interface ParsedPgpMessage {
+    /** For an encrypted message: whether one of the keys opened it. Always `true` for a signed-only one. */
+    decrypted: boolean;
+    /** The recovered MIME entity (PGP/MIME), or for an inline message a `text/plain` entity built around its text. */
+    entityText?: string;
+    /** `undefined` when the message carried no signature. */
+    signature?: PgpSignatureOutcome;
+}
+/** Verifies an RFC 3156 `multipart/signed` message (`protocol="application/pgp-signature"`). Never throws. */
+export declare function parsePgpSignedMessage(contentType: string, body: string, candidates: PgpSignerCandidate[]): Promise<ParsedPgpMessage>;
+/**
+ * Decrypts an RFC 3156 `multipart/encrypted` message with `decryptionKeys`, verifying the signature it carries (a combined signed
+ * and encrypted message, RFC 3156 §6.2, or an inner `multipart/signed`, §6.1) against `candidates` and the keys attached inside.
+ * Never throws.
+ */
+export declare function parsePgpEncryptedMessage(contentType: string, body: string, decryptionKeys: OpenPgpPrivateKey[], candidates: PgpSignerCandidate[]): Promise<ParsedPgpMessage>;
+/** Decrypts an inline OpenPGP message (an armored `PGP MESSAGE` as the whole text body), verifying a signature it carries. Never
+ * throws. */
+export declare function parsePgpInlineEncrypted(armored: string, decryptionKeys: OpenPgpPrivateKey[], candidates: PgpSignerCandidate[]): Promise<ParsedPgpMessage>;
+/** Verifies an inline cleartext-signed message (`BEGIN PGP SIGNED MESSAGE`). Never throws. */
+export declare function parsePgpCleartextSigned(text: string, candidates: PgpSignerCandidate[]): Promise<ParsedPgpMessage>;
+/** The certificates in a list of base64 keys (`PublicKey.publicKey` of OpenPGP entries) - unreadable ones dropped. */
+export declare function readKeysBase64(keys: string[]): Promise<OpenPgpPublicKey[]>;

package/dist/lib/crypto/pgpMessage.js

@@ -0,0 +1,271 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * OpenPGP messages (RFC 3156 PGP/MIME, and the inline forms some clients still send) - the OpenPGP counterpart of
+ * `smimeMessage.ts`, for mail with OpenPGP users (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*). Only ever
+ * imported dynamically: OpenPGP.js is loaded when an OpenPGP message is read or sent.
+ *
+ * Sending writes PGP/MIME only: `multipart/encrypted` (signed and encrypted in one OpenPGP message, RFC 3156 §6.2) and
+ * detached `multipart/signed`. The inner entity carries the protected headers exactly as an S/MIME message does
+ * (`smimeMessage.ts`'s `protectedHeaderLines()`, RFC 9788), marked both `hp=` and `protected-headers="v1"` (the form OpenPGP
+ * mail clients recognise), and its body is base64 so the signed bytes survive transport.
+ *
+ * Reading recovers the inner entity and reports what the signature proved; the trust decision (pins, identity binding,
+ * header checks) is `messageSecurity.ts`'s, the same as for S/MIME.
+ */
+import * as openpgp from "openpgp";
+import { fromBase64 } from "./encoding.js";
+import { bytesToBinaryString, binaryStringToBytes, decodeBodyText, parseMimeEntity, parseParameterizedHeader, splitMultipart } from "./mime.js";
+import { keyEmails, readPublicKeys } from "./openpgp.js";
+import { base64Wrapped, flattenHeaderValue, generateBoundary, protectedHeaderLines, } from "./smimeMessage.js";
+const CRLF = "\r\n";
+/** Builds the inner entity: protected headers, then the body (base64) - wrapped with `attachKey` (an armored public key) in a
+ * `multipart/mixed` when one is given, so a correspondent without our key can import it. */
+function innerEntity(bodyContentType, bodyText, headerBlock, hp, attachKey) {
+    const marks = `hp="${hp}"; protected-headers="v1"`;
+    const bodyPart = [
+        `Content-Type: ${flattenHeaderValue(bodyContentType)}`,
+        `Content-Transfer-Encoding: base64`,
+        "",
+        base64Wrapped(new TextEncoder().encode(bodyText)),
+    ].join(CRLF);
+    if (!attachKey) {
+        return [headerBlock, bodyPart.replace(/^Content-Type: ([^\r\n]*)/, `Content-Type: $1; ${marks}`)].join(CRLF);
+    }
+    const boundary = generateBoundary();
+    return [
+        headerBlock,
+        `Content-Type: multipart/mixed; boundary="${boundary}"; ${marks}`,
+        "",
+        `--${boundary}`,
+        bodyPart,
+        `--${boundary}`,
+        `Content-Type: application/pgp-keys; name="OpenPGP_public_key.asc"`,
+        `Content-Disposition: attachment; filename="OpenPGP_public_key.asc"`,
+        "",
+        attachKey.replace(/\r?\n/g, CRLF).trim(),
+        `--${boundary}--`,
+    ].join(CRLF);
+}
+/**
+ * An RFC 3156 `multipart/encrypted` message: the inner entity (protected headers, the body and - with `attachKey` - our public
+ * key) signed with `signingKey` when given and encrypted to every key in `recipientKeys` in one OpenPGP message. Per the spec's
+ * "Encrypt to Self", `recipientKeys` MUST include the sender's own key.
+ */
+export async function buildPgpEncryptedMessage(bodyContentType, bodyText, protectedHeaders, outerHeaders, recipientKeys, signingKey, attachKey) {
+    const entity = innerEntity(bodyContentType, bodyText, protectedHeaderLines(protectedHeaders, outerHeaders), "cipher", attachKey);
+    const armored = await openpgp.encrypt({
+        message: await openpgp.createMessage({ binary: new TextEncoder().encode(entity) }),
+        encryptionKeys: recipientKeys,
+        ...(signingKey ? { signingKeys: signingKey } : {}),
+        format: "armored",
+    });
+    const boundary = generateBoundary();
+    const body = [
+        `--${boundary}`,
+        `Content-Type: application/pgp-encrypted`,
+        `Content-Description: PGP/MIME version identification`,
+        "",
+        "Version: 1",
+        "",
+        `--${boundary}`,
+        `Content-Type: application/octet-stream; name="encrypted.asc"`,
+        `Content-Description: OpenPGP encrypted message`,
+        `Content-Disposition: inline; filename="encrypted.asc"`,
+        "",
+        armored.replace(/\r?\n/g, CRLF).trim(),
+        `--${boundary}--`,
+    ].join(CRLF);
+    return { contentType: `multipart/encrypted; protocol="application/pgp-encrypted"; boundary="${boundary}"`, body };
+}
+/** The `micalg` of a detached signature: `pgp-` and its hash algorithm's name (RFC 3156 §5). */
+async function micalg(armoredSignature) {
+    const signature = await openpgp.readSignature({ armoredSignature });
+    const id = signature.packets[0]?.hashAlgorithm;
+    const name = id !== undefined && id !== null ? openpgp.enums.read(openpgp.enums.hash, id) : "sha512";
+    return `pgp-${String(name).toLowerCase()}`;
+}
+/** An RFC 3156 detached `multipart/signed` message: the inner entity (protected headers, the body and - with `attachKey` - our
+ * public key), signed with `signingKey`. */
+export async function buildPgpSignedOnlyMessage(bodyContentType, bodyText, protectedHeaders, signingKey, attachKey) {
+    const entity = innerEntity(bodyContentType, bodyText, protectedHeaderLines(protectedHeaders), "clear", attachKey);
+    const signature = await openpgp.sign({
+        message: await openpgp.createMessage({ binary: new TextEncoder().encode(entity) }),
+        signingKeys: signingKey,
+        detached: true,
+        format: "armored",
+    });
+    const boundary = generateBoundary();
+    const body = [
+        `--${boundary}`,
+        entity,
+        `--${boundary}`,
+        `Content-Type: application/pgp-signature; name="OpenPGP_signature.asc"`,
+        `Content-Description: OpenPGP digital signature`,
+        `Content-Disposition: attachment; filename="OpenPGP_signature.asc"`,
+        "",
+        signature.replace(/\r?\n/g, CRLF).trim(),
+        `--${boundary}--`,
+    ].join(CRLF);
+    return {
+        contentType: `multipart/signed; protocol="application/pgp-signature"; micalg=${await micalg(signature)}; boundary="${boundary}"`,
+        body,
+    };
+}
+async function signatureOutcome(signatures, candidates) {
+    let known = false;
+    for (const signature of signatures) {
+        const candidate = candidates.find((c) => c.key.getKeyIDs().some((id) => id.equals(signature.keyID)));
+        if (!candidate) {
+            continue;
+        }
+        known = true;
+        const valid = await signature.verified.then(() => true, () => false);
+        if (valid) {
+            return { status: "verified", candidate, fingerprint: candidate.key.getFingerprint().toLowerCase(), emails: await keyEmails(candidate.key) };
+        }
+    }
+    return known ? { status: "invalid" } : { status: "unknown_key" };
+}
+/** The certificates attached to `entityText` (`application/pgp-keys` parts) - untrusted signer candidates. */
+async function attachedKeys(entityText) {
+    const keys = [];
+    const visit = async (text, depth) => {
+        if (depth > 4) {
+            return;
+        }
+        const entity = parseMimeEntity(text);
+        const type = parseParameterizedHeader(entity.headers["content-type"]);
+        if (type.value === "application/pgp-keys") {
+            keys.push(...(await readPublicKeys(decodeBodyText(entity))));
+        }
+        else if (type.value.startsWith("multipart/") && type.params["boundary"]) {
+            for (const part of splitMultipart(entity.body, type.params["boundary"]).slice(0, 16)) {
+                await visit(part, depth + 1);
+            }
+        }
+    };
+    await visit(entityText, 0);
+    return keys;
+}
+/** Candidates for `entityText`: the given ones, then any key attached to the message (untrusted). */
+async function withAttached(candidates, entityText) {
+    return [...candidates, ...(await attachedKeys(entityText)).map((key) => ({ key, trusted: false }))];
+}
+/** Verifies an RFC 3156 `multipart/signed` message (`protocol="application/pgp-signature"`). Never throws. */
+export async function parsePgpSignedMessage(contentType, body, candidates) {
+    const boundary = parseParameterizedHeader(contentType).params["boundary"];
+    const parts = boundary ? splitMultipart(body, boundary) : [];
+    if (parts.length !== 2) {
+        return { decrypted: true, signature: { status: "invalid" } };
+    }
+    const [signed, signaturePart] = parts;
+    try {
+        const signature = await openpgp.readSignature({ armoredSignature: decodeBodyText(parseMimeEntity(signaturePart)) });
+        const all = await withAttached(candidates, signed);
+        // What was signed is the part in canonical CRLF form (RFC 3156 §5).
+        const canonical = signed.replace(/\r?\n/g, CRLF);
+        const verification = await openpgp.verify({
+            message: await openpgp.createMessage({ binary: binaryStringToBytes(canonical) }),
+            signature,
+            verificationKeys: all.map((c) => c.key),
+            expectSigned: false,
+        });
+        return { decrypted: true, entityText: signed, signature: await signatureOutcome(verification.signatures, all) };
+    }
+    catch {
+        return { decrypted: true, signature: { status: "invalid" } };
+    }
+}
+/** The armored OpenPGP message in an RFC 3156 `multipart/encrypted` body (its second part), or `undefined`. */
+function encryptedPayload(contentType, body) {
+    const boundary = parseParameterizedHeader(contentType).params["boundary"];
+    const parts = boundary ? splitMultipart(body, boundary) : [];
+    return parts.length === 2 ? decodeBodyText(parseMimeEntity(parts[1])) : undefined;
+}
+/**
+ * Decrypts an RFC 3156 `multipart/encrypted` message with `decryptionKeys`, verifying the signature it carries (a combined signed
+ * and encrypted message, RFC 3156 §6.2, or an inner `multipart/signed`, §6.1) against `candidates` and the keys attached inside.
+ * Never throws.
+ */
+export async function parsePgpEncryptedMessage(contentType, body, decryptionKeys, candidates) {
+    const payload = encryptedPayload(contentType, body);
+    if (!payload || decryptionKeys.length === 0) {
+        return { decrypted: false };
+    }
+    let data;
+    let signed;
+    try {
+        const result = await openpgp.decrypt({ message: await openpgp.readMessage({ armoredMessage: payload }), decryptionKeys, format: "binary", expectSigned: false });
+        data = result.data;
+        signed = result.signatures.length > 0;
+    }
+    catch {
+        return { decrypted: false };
+    }
+    const entityText = bytesToBinaryString(data);
+    const inner = parseMimeEntity(entityText);
+    const innerType = parseParameterizedHeader(inner.headers["content-type"]);
+    if (!signed && innerType.value === "multipart/signed" && innerType.params["protocol"]?.toLowerCase() === "application/pgp-signature") {
+        const innerSigned = await parsePgpSignedMessage(inner.headers["content-type"], inner.body, candidates);
+        return { decrypted: true, entityText: innerSigned.entityText ?? entityText, signature: innerSigned.signature };
+    }
+    if (!signed) {
+        return { decrypted: true, entityText };
+    }
+    // The keys attached inside are only known now: verify the signature against them and the given ones together.
+    const all = await withAttached(candidates, entityText);
+    if (all.length === 0) {
+        return { decrypted: true, entityText, signature: { status: "unknown_key" } };
+    }
+    const verified = await openpgp.decrypt({
+        message: await openpgp.readMessage({ armoredMessage: payload }),
+        decryptionKeys,
+        verificationKeys: all.map((c) => c.key),
+        format: "binary",
+        expectSigned: false,
+    });
+    return { decrypted: true, entityText, signature: await signatureOutcome(verified.signatures, all) };
+}
+/** A `text/plain` entity for an inline message's recovered text. */
+function plainEntity(text) {
+    return bytesToBinaryString(new TextEncoder().encode(`Content-Type: text/plain; charset=utf-8${CRLF}${CRLF}${text}`));
+}
+/** Decrypts an inline OpenPGP message (an armored `PGP MESSAGE` as the whole text body), verifying a signature it carries. Never
+ * throws. */
+export async function parsePgpInlineEncrypted(armored, decryptionKeys, candidates) {
+    if (decryptionKeys.length === 0) {
+        return { decrypted: false };
+    }
+    try {
+        const result = await openpgp.decrypt({
+            message: await openpgp.readMessage({ armoredMessage: armored }),
+            decryptionKeys,
+            verificationKeys: candidates.map((c) => c.key),
+            expectSigned: false,
+        });
+        const signature = result.signatures.length > 0 ? await signatureOutcome(result.signatures, candidates) : undefined;
+        return { decrypted: true, entityText: plainEntity(String(result.data)), ...(signature ? { signature } : {}) };
+    }
+    catch {
+        return { decrypted: false };
+    }
+}
+/** Verifies an inline cleartext-signed message (`BEGIN PGP SIGNED MESSAGE`). Never throws. */
+export async function parsePgpCleartextSigned(text, candidates) {
+    try {
+        const message = await openpgp.readCleartextMessage({ cleartextMessage: text });
+        const verification = await openpgp.verify({ message, verificationKeys: candidates.map((c) => c.key), expectSigned: false });
+        return { decrypted: true, entityText: plainEntity(message.getText()), signature: await signatureOutcome(verification.signatures, candidates) };
+    }
+    catch {
+        return { decrypted: true, signature: { status: "invalid" } };
+    }
+}
+/** The certificates in a list of base64 keys (`PublicKey.publicKey` of OpenPGP entries) - unreadable ones dropped. */
+export async function readKeysBase64(keys) {
+    const read = await Promise.all(keys.map((key) => readPublicKeys(fromBase64(key))));
+    return read.flat();
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Shared mailboxes' zero-access keys (restapi `specs/search.md` §3 *Shared Mailboxes*). A mailbox someone else owns, or that has no owner,
+ * has no master key its members know: its zero-access private key is instead wrapped to each member's own zero-access certificate
+ * (member key wraps), and a member opens it with the zero-access key of a mailbox they own - so a member unlocks it without a password,
+ * once their own mailbox is unlocked. Members get the ability to read, never the master key, signing key or encryption keys.
+ *
+ * `unlockSharedMailbox()` opens a shared mailbox for its member. `maintainSharedMailbox()` is what the client of the owner, or of a member
+ * with full access, does in the background: provisions a key for a mailbox without an owner, wraps the keys for members still waiting,
+ * and - once someone who held the key has left - rotates it, so new mail is encrypted to a key they never had. A mailbox without an owner
+ * has no master key for escrow to open, so when it is assigned to an escrow scope each of its keys is also wrapped to the scope's
+ * certificate: with a new key in the same write, and for keys the scope is still missing (`escrowPending`) in the background.
+ */
+import { type ApiClient } from "../util/api.js";
+/** What `unlockSharedMailbox()` found. */
+export type SharedUnlockOutcome = 
+/** Its keys are open in this session. */
+"unlocked"
+/** The caller is a member but holds no wrap yet: another member's client shares the key with them shortly. */
+ | "pending"
+/** The caller is a member, but none of their own mailboxes is unlocked to open their wraps with. */
+ | "own_keys_locked"
+/** Not a shared mailbox of the caller's (they own it, or have no member access): its own unlock applies. */
+ | "not_shared";
+/**
+ * Opens shared mailbox `mailboxUid` for its member, with no password: their member wraps, opened with the zero-access keys of a mailbox they
+ * own and have unlocked, become this session's keys for it (`installSharedSession()`). See `SharedUnlockOutcome` for when it can't.
+ *
+ * `refresh`: a shared session already open is opened again when it lacks the mailbox's active key and the member now holds a wrap of it -
+ * after a rotation, new mail is sealed to a key the session doesn't have. Its `masterKey` secret is kept, so the local index stays readable.
+ */
+export declare function unlockSharedMailbox(mailboxUid: string, client?: ApiClient, refresh?: boolean): Promise<SharedUnlockOutcome>;
+/** What `maintainSharedMailbox()` did. */
+export interface SharedMaintenance {
+    provisioned: boolean;
+    rotated: boolean;
+    /** Wraps added for waiting members. */
+    wrapped: number;
+    /** Wraps of older keys the server refused for waiting members (tried again on the next pass). */
+    refused: number;
+    /** Departed users whose wraps were removed. */
+    removed: number;
+    /** Keys wrapped for the mailbox's escrow scope. */
+    escrowed: number;
+    /**
+     * The server's reason when it refused (400) the new key of a pending rotation - e.g. the vault couldn't hold the new key's member wraps
+     * next to those it holds - so the current key stays active and members keep reading; the rotation is tried again on the next pass.
+     */
+    rotationRefused?: string;
+}
+/**
+ * The background care of a shared mailbox, run by the client of its owner or of a member with full access (`status.manager`); nothing for
+ * anyone else, or while the keys it needs are locked:
+ *
+ * A mailbox without an owner and without a key gets one (unless the administrator disallows zero-access), wrapped for every member who has a
+ * certificate. Once a user who held the active key has left (`rotationPending`), a new key replaces it - enrolled by the owner with their
+ * master key (`provisionZeroAccessKey()`), or for a mailbox without an owner with the members' wraps - and then the departed users' wraps
+ * are removed. Members still waiting (`pending`) get wraps of every key this client can open, one write per key with the active key's
+ * first (a refused older key doesn't stop the rest), and the escrow scope of a mailbox without an owner gets copies of the keys it is
+ * missing (`escrowPending`). A rotation the server refuses (400) is reported in `rotationRefused`, not thrown: the current key stays active
+ * and the rest of the pass goes ahead.
+ */
+export declare function maintainSharedMailbox(mailboxUid: string, mailboxAddress: string, client?: ApiClient): Promise<SharedMaintenance>;