@rapidmx/web-client 0.36.0 → 0.37.1

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

@@ -24,18 +24,28 @@ export type SharedUnlockOutcome =
 /**
  * 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): Promise<SharedUnlockOutcome>;
+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
@@ -44,7 +54,9 @@ export interface SharedMaintenance {
  * 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, and the escrow scope of a mailbox without an
- * owner gets copies of the keys it is missing (`escrowPending`).
+ * 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>;

package/dist/lib/crypto/sharedMailboxKeys.js

@@ -17,8 +17,9 @@
 import { ApiRequestError } from "../util/api.js";
 import { fromBase64, toBase64 } from "./encoding.js";
 import { enrollSharedZeroAccessKey, getEncryptionPolicy, getEscrowInfo, getKeyVault, getMyMemberKeyWraps, getSharedKeyStatus, putMemberKeyWraps, putZeroAccessEscrowWraps, removeMemberKeyWraps, } from "./keyvaultApi.js";
+import { certificateHoldsKey } from "./keyPairMatch.js";
 import { exportPrivateKeyPkcs8, generateKeyPairWithCsr, importPrivateKeyPkcs8 } from "./keys.js";
-import { getUnlockedKeys, installSharedSession, personalSessions, sharedUnlockGeneration, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE, } from "./keySession.js";
+import { addZeroAccessKey, getUnlockedKeys, installSharedSession, personalSessions, sharedUnlockGeneration, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE, } from "./keySession.js";
 import { buildAad, openWithKey } from "./masterKey.js";
 import { decryptEnvelopedDataWithKeys, encryptForRecipients } from "./smime.js";
 import { provisionZeroAccessKey } from "./zeroAccessKey.js";
@@ -63,9 +64,13 @@ function keyOrder(status) {
 /**
  * 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 async function unlockSharedMailbox(mailboxUid, client) {
-    if (getUnlockedKeys(mailboxUid)) {
+export async function unlockSharedMailbox(mailboxUid, client, refresh = false) {
+    const existing = getUnlockedKeys(mailboxUid);
+    if (existing && !(refresh && existing.shared)) {
         return "unlocked";
     }
     const generation = sharedUnlockGeneration(mailboxUid);
@@ -75,14 +80,22 @@ export async function unlockSharedMailbox(mailboxUid, client) {
     }
     catch (err) {
         if (err instanceof ApiRequestError && (err.status === 403 || err.status === 404)) {
-            return "not_shared";
+            return existing ? "unlocked" : "not_shared";
         }
         throw err;
     }
+    const holdsActive = (keys) => !!keys?.some((key) => key.fingerprint === status.activeKeyFingerprint);
+    if (existing && (!status.activeKeyFingerprint || holdsActive(existing.zeroAccessKeys))) {
+        return "unlocked";
+    }
     if (status.role !== "member") {
-        return "not_shared";
+        return existing ? "unlocked" : "not_shared";
     }
     const wraps = await getMyMemberKeyWraps(mailboxUid, client);
+    // Nothing new to open yet: the active key's wrap is still on its way.
+    if (existing && !holdsActive(wraps.map((wrap) => ({ fingerprint: wrap.zeroAccessKeyFingerprint })))) {
+        return "unlocked";
+    }
     if (wraps.length === 0) {
         return "pending";
     }
@@ -99,29 +112,48 @@ export async function unlockSharedMailbox(mailboxUid, client) {
         }
         const pkcs8 = unwrapped.pkcs8;
         try {
+            // The certificate is the server's: one that isn't this key's must never be what this session seals to.
+            if (!(await certificateHoldsKey(fromBase64(certificate.publicKey), pkcs8))) {
+                continue;
+            }
             secret ?? (secret = await sessionSecret(pkcs8));
             const privateKey = await importPrivateKeyPkcs8(pkcs8, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"]);
             opened.push({ fingerprint: wrap.zeroAccessKeyFingerprint, certDer: fromBase64(certificate.publicKey), privateKey });
             openedWith.add(unwrapped.openedWith);
         }
         catch {
-            // A wrap that doesn't hold a usable key is skipped; the others still open the mailbox.
+            // A wrap that doesn't hold a usable key (or one its certificate doesn't match) is skipped; the others still open the mailbox.
         }
         finally {
             pkcs8.fill(0);
         }
     }
     if (!secret || opened.length === 0) {
-        return "own_keys_locked";
+        return existing ? "unlocked" : "own_keys_locked";
+    }
+    if (existing) {
+        // Opened again: the secret the local index key is derived from stays the one the session started with.
+        secret.fill(0);
+        secret = new Uint8Array(existing.masterKey);
     }
     const unlocked = { masterKey: secret, zeroAccessKeys: opened, openedWith: [...openedWith] };
     installSharedSession(mailboxUid, unlocked, generation);
     return "unlocked";
 }
 /** The PKCS#8 of every zero-access key of `mailboxUid` the caller can open, by fingerprint - from the vault with the owner's unlocked master
- * key, or from the caller's own member wraps. The caller zeroes them. */
+ * key, or from the caller's own member wraps. Only keys whose certificate in `status` (the server's) is really theirs: a key is wrapped
+ * for members and escrow under that certificate's fingerprint, so a mismatched one is left out. The caller zeroes them. */
 async function openPrivateKeys(mailboxUid, status, ownerUnlocked, client) {
     const keys = new Map();
+    const keep = async (fingerprint, pkcs8) => {
+        const certificate = status.zeroAccessKeys.find((key) => key.fingerprint === fingerprint);
+        if (certificate && (await certificateHoldsKey(fromBase64(certificate.publicKey), pkcs8))) {
+            keys.set(fingerprint, pkcs8);
+        }
+        else {
+            pkcs8.fill(0);
+        }
+    };
     if (ownerUnlocked) {
         const vault = await getKeyVault(mailboxUid, client);
         const aad = buildAad(mailboxUid, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE);
@@ -129,7 +161,7 @@ async function openPrivateKeys(mailboxUid, status, ownerUnlocked, client) {
             const wrapped = vault.wrappedKeys.find((w) => w.fingerprint === key.fingerprint && w.useType === "zero-access");
             if (wrapped) {
                 try {
-                    keys.set(key.fingerprint, await openWithKey(ownerUnlocked.masterKey, wrapped, aad));
+                    await keep(key.fingerprint, await openWithKey(ownerUnlocked.masterKey, wrapped, aad));
                 }
                 catch {
                     // Sealed under a master key since replaced: not this device's to share.
@@ -142,7 +174,7 @@ async function openPrivateKeys(mailboxUid, status, ownerUnlocked, client) {
     for (const wrap of await getMyMemberKeyWraps(mailboxUid, client)) {
         const unwrapped = await openWrap(wrap, own);
         if (unwrapped) {
-            keys.set(wrap.zeroAccessKeyFingerprint, unwrapped.pkcs8);
+            await keep(wrap.zeroAccessKeyFingerprint, unwrapped.pkcs8);
         }
     }
     return keys;
@@ -154,9 +186,21 @@ async function wrapFor(member, pkcs8) {
         cms: toBase64(await encryptForRecipients(pkcs8, [fromBase64(member.certificate.publicKey)])),
     };
 }
-/** The members with a certificate of their own - the ones a key can be wrapped for. */
+/** The members with a certificate of their own - the ones a key can be wrapped for. A certificate listed under the fingerprint of one of
+ * this user's own opened zero-access keys must be that key's certificate (checked against its private key at unlock): one the server
+ * swapped is left out, so a wrap meant for this user never goes to a key that isn't theirs. */
 function wrappable(status) {
-    return status.members.filter((member) => !!member.certificate);
+    const own = ownZeroAccessKeys();
+    return status.members.filter((member) => {
+        if (!member.certificate) {
+            return false;
+        }
+        const mine = own.find((key) => key.fingerprint === member.certificate.fingerprint);
+        return !mine || sameBytes(mine.certDer, fromBase64(member.certificate.publicKey));
+    });
+}
+function sameBytes(a, b) {
+    return a.length === b.length && a.every((byte, index) => byte === b[index]);
 }
 /** `pkcs8` wrapped to the certificate of the escrow scope `escrow` describes. */
 async function escrowWrapFor(escrow, pkcs8) {
@@ -184,11 +228,13 @@ async function enrollNewSharedKey(mailboxUid, mailboxAddress, status, client) {
  * 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, and the escrow scope of a mailbox without an
- * owner gets copies of the keys it is missing (`escrowPending`).
+ * 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 async function maintainSharedMailbox(mailboxUid, mailboxAddress, client) {
-    const result = { provisioned: false, rotated: false, wrapped: 0, removed: 0, escrowed: 0 };
+    const result = { provisioned: false, rotated: false, wrapped: 0, refused: 0, removed: 0, escrowed: 0 };
     let status = await getSharedKeyStatus(mailboxUid, client);
     if (!status.manager || (status.members.length === 0 && status.departed.length === 0)) {
         return result;
@@ -206,15 +252,27 @@ export async function maintainSharedMailbox(mailboxUid, mailboxAddress, client)
         result.provisioned = true;
     }
     else if (status.rotationPending) {
-        if (status.ownerless) {
-            status = await enrollNewSharedKey(mailboxUid, mailboxAddress, status, client);
+        try {
+            if (status.ownerless) {
+                status = await enrollNewSharedKey(mailboxUid, mailboxAddress, status, client);
+            }
+            else {
+                const vault = await getKeyVault(mailboxUid, client);
+                const { key } = await provisionZeroAccessKey(mailboxUid, mailboxAddress, ownerUnlocked.masterKey, vault.masterKeyGeneration, client);
+                // The owner's open session gets the new key as its active one, as `ensureZeroAccessKey()` does: new mail is sealed to it.
+                addZeroAccessKey(mailboxUid, ownerUnlocked, key);
+                status = await getSharedKeyStatus(mailboxUid, client);
+            }
+            result.rotated = true;
         }
-        else {
-            const vault = await getKeyVault(mailboxUid, client);
-            await provisionZeroAccessKey(mailboxUid, mailboxAddress, ownerUnlocked.masterKey, vault.masterKeyGeneration, client);
-            status = await getSharedKeyStatus(mailboxUid, client);
+        catch (err) {
+            // Refused before any key was issued (restapi: the vault can't hold the new key's member wraps next to those it holds): the
+            // current key stays active, so the rest of the pass - waiting members' wraps of it - still goes ahead. Anything else throws.
+            if (!(err instanceof ApiRequestError) || err.status !== 400) {
+                throw err;
+            }
+            result.rotationRefused = err.message;
         }
-        result.rotated = true;
     }
     // The departed hold no wrap of the active key any more (or never did): their old wraps go.
     if (!status.rotationPending) {
@@ -228,17 +286,32 @@ export async function maintainSharedMailbox(mailboxUid, mailboxAddress, client)
     if (missing.length > 0 || escrowPending.length > 0) {
         const keys = await openPrivateKeys(mailboxUid, status, ownerUnlocked, client);
         try {
-            const wraps = [];
-            for (const member of missing) {
-                for (const [fingerprint, pkcs8] of keys) {
+            // One write per key, the active key's first: it alone opens new mail, so a refused backfill of an older key (the server bounds
+            // each key's wraps and the vault's total) never keeps a member from it. A failed older key is left for the next pass.
+            const order = keyOrder(status);
+            for (const [fingerprint, pkcs8] of [...keys].sort(([a], [b]) => order(a) - order(b))) {
+                const wraps = [];
+                for (const member of missing) {
                     if (!member.wrapped.includes(fingerprint)) {
                         wraps.push({ ...(await wrapFor(member, pkcs8)), zeroAccessKeyFingerprint: fingerprint });
                     }
                 }
-            }
-            if (wraps.length > 0) {
-                await putMemberKeyWraps(mailboxUid, wraps, client);
-                result.wrapped = wraps.length;
+                if (wraps.length === 0) {
+                    continue;
+                }
+                if (fingerprint === status.activeKeyFingerprint) {
+                    await putMemberKeyWraps(mailboxUid, wraps, client);
+                    result.wrapped += wraps.length;
+                }
+                else {
+                    try {
+                        await putMemberKeyWraps(mailboxUid, wraps, client);
+                        result.wrapped += wraps.length;
+                    }
+                    catch {
+                        result.refused += wraps.length;
+                    }
+                }
             }
             const held = escrowPending.filter((fingerprint) => keys.has(fingerprint));
             if (held.length > 0) {

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

@@ -13,6 +13,14 @@ export interface ProtectedHeaders {
  * (Section 3.3). Applied to produce the OUTER, unprotected envelope's headers from the real
  * (protected) ones; `From`/`To`/`Cc`/`Date` pass through unchanged, `Subject` is obscured. */
 export declare function applyBaselineOuterHeaders(headers: ProtectedHeaders): ProtectedHeaders;
+/** @internal Shared with `pgpMessage.ts`. */
+export declare function base64Wrapped(bytes: Uint8Array): string;
+/** @internal Shared with `pgpMessage.ts`. */
+export declare function generateBoundary(): string;
+/** Strips CR/LF/NUL from a header value that has no further encoding (Date, Message-ID, Content-Type). */
+export declare function flattenHeaderValue(value: string): string;
+/** @internal Shared with `pgpMessage.ts`: the protected header block of an inner entity (with `HP-Outer:` copies of `hpOuter`). */
+export declare function protectedHeaderLines(headers: ProtectedHeaders, hpOuter?: ProtectedHeaders): string;
 /** One MIME entity's worth of headers-beyond-Content-Type plus body, ready for a caller (the actual
  * outbound-message compose step, built on top of this module) to combine with the outer envelope's
  * own `From`/`To`/`Subject`/`Date`/`Message-ID`. */
@@ -106,6 +114,17 @@ export interface ParsedEncryptedMessage {
  * (`messageId` has no `HP-Outer` counterpart; only the fields the outer envelope itself carries do).
  * Exported so `messageSecurity.ts` can build one from a received message's real outer envelope. */
 export type ComparableOuterHeaders = Partial<Pick<ProtectedHeaders, "from" | "to" | "cc" | "date" | "subject">>;
+/** Extracts the outer-envelope header values RFC 9788's `HP-Outer: <Field>: <value>` mechanism embeds
+ * inside an encrypted message's protected content - one line per outer header, all sharing the literal
+ * field name `HP-Outer`, which `splitHeadersAndBody()`'s own flat header map can hold only the last of
+ * (a real bug if reused for this - JSON/`Record` keys aren't multi-valued). Scans the raw header block
+ * text directly instead. Returns `undefined` when no `HP-Outer:` lines are present at all, so a caller
+ * can distinguish "nothing to compare" from "compared and everything matched". */
+export declare function extractHpOuterHeaders(fields: MimeHeaderField[]): ComparableOuterHeaders | undefined;
+/** `true` when every field `hpOuter` actually carries matches `actualOuterHeaders`' value for that same
+ * field - a field `hpOuter` doesn't carry (e.g. no `Cc` on this message) is not compared, since RFC
+ * 9788 never claims coverage for it either way. */
+export declare function outerHeadersMatch(hpOuter: ComparableOuterHeaders, actualOuterHeaders: ComparableOuterHeaders): boolean;
 /** Decrypts (and, if present, verifies the inner signature of) a message built by
  * `buildEncryptedMessage()`. Returns `{ decrypted: false }` (never throws) for anything malformed or
  * undecryptable with the given key — the caller's own concern is distinguishing "wrong key" from
@@ -130,3 +149,5 @@ export declare function splitHeadersAndBody(entity: string): {
     body: string;
     rawHeaderBlock: string;
 };
+/** @internal Shared with `pgpMessage.ts`. */
+export declare function headersToProtectedHeaders(headers: Record<string, string>): ProtectedHeaders;