@rapidmx/web-client 0.34.0 → 0.36.0

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

@@ -34,6 +34,7 @@
  * accepted or automatic rotation still verifies.
  */
 import { MimeAttachment, MimeHeaderField } from "./mime.js";
+import { type DecryptionKey } from "./smime.js";
 import { ProtectedHeaders } from "./smimeMessage.js";
 import { type PublicKey } from "./keyvaultApi.js";
 import { type SealKeyMaterial, type SealedVerificationState } from "./verificationSeal.js";
@@ -49,7 +50,7 @@ export { signingKeyFingerprints } from "./keyvaultApi.js";
  * `sealedState`, `signerFingerprint`, the recovered content, `liveState`/`liveSignatureFailureReason`, and
  * `laterCompromised` when the signer key has since been revoked as compromised. A UI should show it as "verified when
  * first opened" - distinct from the live verified states, and with a warning when `laterCompromised` is set. */
-export type MessageSecurityState = "encrypted" | "signed_verified" | "encrypted_verified" | "signed_unverified_signer" | "encrypted_unverified_signer" | "signature_failed" | "verified_at_first_open" | "unprotected";
+export type MessageSecurityState = "encrypted" | "signed_verified" | "encrypted_verified" | "signed_unverified_signer" | "encrypted_unverified_signer" | "signature_failed" | "verified_at_first_open" | "protected_at_rest" | "unprotected";
 /** Why a message is `"signature_failed"`. `invalid_signature`: the CMS signature itself is malformed or
  * doesn't verify over the content (or a `multipart/signed` body doesn't hold exactly two parts).
  * `signer_key_changed`: pinned fingerprints were supplied and the signer certificate matches none of them, but it
@@ -92,6 +93,13 @@ export interface MessageSecurityResult {
      * since-rotated key, non-AEAD content encryption, or corrupt/foreign data) - the caller should keep
      * showing whatever `GET /:id/content` already produced alongside this explanation. */
     decryptError?: string;
+    /** Set when the stored message was sealed at rest by the server (restapi `specs/search.md` §3) and opened here with the mailbox's
+     * zero-access key. `state` then describes the original message inside: `protected_at_rest` when it arrived unprotected, or its own
+     * signed/encrypted state otherwise. */
+    zeroAccess?: boolean;
+    /** With `zeroAccess`: the original's calendar file (`extractCalendarText()`), which the server can't read from the sealed copy - the
+     * client sends it with the invitation endpoints. Absent when the message carries none. */
+    calendar?: string;
     /** See `ParsedEncryptedMessage.headerTamperDetected`'s own doc comment - a deliberately separate,
      * orthogonal signal from `state`, since RFC 9788's `HP-Outer` is written on every encrypted message
      * regardless of whether it's also signed. `undefined` for anything that isn't an encrypted message
@@ -200,7 +208,28 @@ export interface MessageSecurityKeys {
         privateKey: CryptoKey;
     }[];
     signingFingerprint?: string;
+    /** The mailbox's zero-access keys (`keySession.ts`'s `UnlockedKeys.zeroAccessKeys`) - what opens a message the server sealed at
+     * rest on arrival. */
+    zeroAccessKeys?: {
+        certDer: Uint8Array;
+        privateKey: CryptoKey;
+    }[];
 }
+/**
+ * The subject and preview of a zero-access message (`Message.zeroAccess.sealedSummary`, base64 CMS of JSON `{ subject, preview }`),
+ * decrypted with the mailbox's zero-access keys - a few hundred bytes, so a message list shows real subjects without downloading
+ * each message. `undefined` when no key opens it or it isn't a summary.
+ */
+export declare function openZeroAccessSummary(sealedSummary: string, keys: DecryptionKey[] | undefined): Promise<{
+    subject: string;
+    preview: string;
+} | undefined>;
+/**
+ * The original MIME (as a binary string) of a stored message the server sealed at rest, opened with `unlocked.zeroAccessKeys` -
+ * `undefined` when it isn't a sealed message or no key opens it. For what needs the original itself, e.g. reporting it to the spam
+ * filter (`reportMessage()`'s `rawMessage`).
+ */
+export declare function openZeroAccessMessage(rawMime: string, unlocked: MessageSecurityKeys | undefined): Promise<string | undefined>;
 /** Options for `evaluateMessageSecurityWithSeal()`. */
 export interface VerificationSealOptions {
     mailboxUid: string;

package/dist/lib/crypto/messageSecurity.js

@@ -37,9 +37,9 @@
  * `untrusted_signer`. Previously pinned keys count as pins (see `signingKeyFingerprints()`), so mail signed before an
  * accepted or automatic rotation still verifies.
  */
-import { decodeHeaderText, extractAddresses, parseMimeEntity, parseParameterizedHeader, plainTextToHtml } from "./mime.js";
-import { toBase64 } from "./encoding.js";
-import { computeCertFingerprint, extractCertificateEmails } from "./smime.js";
+import { bytesToBinaryString, decodeBase64Text, decodeHeaderText, extractAddresses, extractAttachments, extractCalendarText, extractDisplayBody, parseMimeEntity, parseParameterizedHeader, plainTextToHtml, } from "./mime.js";
+import { fromBase64, toBase64 } from "./encoding.js";
+import { computeCertFingerprint, decryptEnvelopedDataWithKeys, extractCertificateEmails } from "./smime.js";
 import { parseEncryptedMessageWithKeys, parseSignedOnlyMessage } from "./smimeMessage.js";
 import { isTrustedForVerification } from "./keyvaultApi.js";
 import { KeysLockedError } from "./masterKey.js";
@@ -174,7 +174,55 @@ function checkIdentityAndHeaders(input, certDer) {
 export async function evaluateMessageSecurity(rawMime, unlocked, pinnedSignerFingerprints, readerAddress) {
     return (await evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress)).result;
 }
-async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress) {
+/**
+ * The subject and preview of a zero-access message (`Message.zeroAccess.sealedSummary`, base64 CMS of JSON `{ subject, preview }`),
+ * decrypted with the mailbox's zero-access keys - a few hundred bytes, so a message list shows real subjects without downloading
+ * each message. `undefined` when no key opens it or it isn't a summary.
+ */
+export async function openZeroAccessSummary(sealedSummary, keys) {
+    if (!keys?.length) {
+        return undefined;
+    }
+    try {
+        const json = JSON.parse(new TextDecoder().decode(await decryptEnvelopedDataWithKeys(fromBase64(sealedSummary), keys)));
+        const { subject, preview } = (json ?? {});
+        return typeof subject === "string" && typeof preview === "string" ? { subject, preview } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The original MIME (as a binary string) of a stored message the server sealed at rest, opened with `unlocked.zeroAccessKeys` -
+ * `undefined` when it isn't a sealed message or no key opens it. For what needs the original itself, e.g. reporting it to the spam
+ * filter (`reportMessage()`'s `rawMessage`).
+ */
+export async function openZeroAccessMessage(rawMime, unlocked) {
+    const { headers, body } = parseMimeEntity(rawMime);
+    const rawContentType = headers["content-type"];
+    if (!unlocked?.zeroAccessKeys?.length || !rawContentType || !isEncryptedContentType(parseParameterizedHeader(rawContentType))) {
+        return undefined;
+    }
+    return openZeroAccess(body, unlocked.zeroAccessKeys);
+}
+/**
+ * The original MIME of a message the server sealed at rest (restapi `specs/search.md` §3) - the stored S/MIME `enveloped-data`
+ * message's content, decrypted with one of `keys` - or `undefined` when none of them opens it. Only the server ever encrypts to a
+ * zero-access key (it is never published), so a message that opens with one was sealed at rest, never sent end-to-end.
+ */
+async function openZeroAccess(body, keys) {
+    const der = decodeBase64Text(body);
+    if (!der) {
+        return undefined;
+    }
+    try {
+        return bytesToBinaryString(await decryptEnvelopedDataWithKeys(der, keys));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerAddress, sealedAtRest = false) {
     const { headers, body, fields } = parseMimeEntity(rawMime);
     const rawContentType = headers["content-type"];
     if (!rawContentType) {
@@ -248,6 +296,34 @@ async function evaluateLive(rawMime, unlocked, pinnedSignerFingerprints, readerA
             kind: "signed",
         };
     }
+    // A message the server sealed at rest: evaluate the original it holds - which may itself be signed or end-to-end encrypted -
+    // and report one that was unprotected when it arrived as `protected_at_rest`, with its content.
+    if (isEncryptedContentType(contentType) && !sealedAtRest && unlocked?.zeroAccessKeys?.length) {
+        const original = await openZeroAccess(body, unlocked.zeroAccessKeys);
+        if (original !== undefined) {
+            const inner = await evaluateLive(original, unlocked, pinnedSignerFingerprints, readerAddress, true);
+            const entity = parseMimeEntity(original);
+            const subject = entity.headers["subject"];
+            const calendarText = extractCalendarText(entity);
+            const calendar = calendarText !== undefined ? { calendar: calendarText } : {};
+            if (inner.result.state !== "unprotected") {
+                // The stored message's own Subject is the placeholder: the original's stands in when the inner result has none.
+                const fallbackSubject = inner.result.subject === undefined && subject !== undefined ? { subject: decodeHeaderText(subject) } : {};
+                return { ...inner, result: { ...inner.result, ...fallbackSubject, ...calendar, zeroAccess: true } };
+            }
+            return {
+                result: {
+                    state: "protected_at_rest",
+                    zeroAccess: true,
+                    ...calendar,
+                    ...renderDisplayBody(extractDisplayBody(entity)),
+                    ...(subject !== undefined ? { subject: decodeHeaderText(subject) } : {}),
+                    attachments: extractAttachments(entity),
+                },
+                kind: "other",
+            };
+        }
+    }
     if (isEncryptedContentType(contentType)) {
         // The active key first, then the retained older ones (see `keySession.ts`'s `retainedEncryptionKeys`), so mail
         // encrypted to a key since replaced still opens. Only ever used to decrypt here - never to encrypt or sign.

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

@@ -135,6 +135,11 @@ export interface MimeAttachment {
  * reported as one attachment, never expanded.
  */
 export declare function extractAttachments(entity: MimeEntity, depth?: number): MimeAttachment[];
+/**
+ * The text of the first calendar file in `entity` (descending into multipart children, bounded depth): a `text/calendar` or
+ * `application/ics` leaf, whether a body alternative (as Outlook sends an invitation) or an attached `.ics`. `undefined` when there is none.
+ */
+export declare function extractCalendarText(entity: MimeEntity, depth?: number): string | undefined;
 /** HTML-escapes plain text and wraps it in a whitespace-preserving `<pre>`, so a `text/plain` body can be
  * rendered through the same HTML path without ever being interpreted as markup. */
 export declare function plainTextToHtml(text: string): string;

package/dist/lib/crypto/mime.js

@@ -478,6 +478,31 @@ export function extractAttachments(entity, depth = 0) {
         },
     ];
 }
+/**
+ * The text of the first calendar file in `entity` (descending into multipart children, bounded depth): a `text/calendar` or
+ * `application/ics` leaf, whether a body alternative (as Outlook sends an invitation) or an attached `.ics`. `undefined` when there is none.
+ */
+export function extractCalendarText(entity, depth = 0) {
+    const contentType = parseParameterizedHeader(entity.headers["content-type"] ?? "text/plain");
+    if (contentType.value.startsWith("multipart/")) {
+        const boundary = contentType.params["boundary"];
+        if (!boundary || depth >= MAX_MULTIPART_DEPTH) {
+            return undefined;
+        }
+        for (const part of splitMultipart(entity.body, boundary)) {
+            const found = extractCalendarText(parseMimeEntity(part), depth + 1);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    if (contentType.value !== "text/calendar" && contentType.value !== "application/ics") {
+        return undefined;
+    }
+    const bytes = decodeBodyBytes(entity);
+    return bytes ? new TextDecoder().decode(bytes) : undefined;
+}
 /** HTML-escapes plain text and wraps it in a whitespace-preserving `<pre>`, so a `text/plain` body can be
  * rendered through the same HTML path without ever being interpreted as markup. */
 export function plainTextToHtml(text) {

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

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+export declare function unlockSharedMailbox(mailboxUid: string, client?: ApiClient): Promise<SharedUnlockOutcome>;
+/** What `maintainSharedMailbox()` did. */
+export interface SharedMaintenance {
+    provisioned: boolean;
+    rotated: boolean;
+    /** Wraps added for waiting members. */
+    wrapped: number;
+    /** Departed users whose wraps were removed. */
+    removed: number;
+    /** Keys wrapped for the mailbox's escrow scope. */
+    escrowed: number;
+}
+/**
+ * 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, and the escrow scope of a mailbox without an
+ * owner gets copies of the keys it is missing (`escrowPending`).
+ */
+export declare function maintainSharedMailbox(mailboxUid: string, mailboxAddress: string, client?: ApiClient): Promise<SharedMaintenance>;

package/dist/lib/crypto/sharedMailboxKeys.js

@@ -0,0 +1,264 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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 { 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 { exportPrivateKeyPkcs8, generateKeyPairWithCsr, importPrivateKeyPkcs8 } from "./keys.js";
+import { 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";
+/** Domain-separation prefix of the secret a shared session's `masterKey` stands for. */
+const SESSION_SECRET_LABEL = new TextEncoder().encode("rapidmx-shared-mailbox-session-v1:");
+async function sessionSecret(pkcs8) {
+    const input = new Uint8Array(SESSION_SECRET_LABEL.length + pkcs8.length);
+    input.set(SESSION_SECRET_LABEL);
+    input.set(pkcs8, SESSION_SECRET_LABEL.length);
+    try {
+        return new Uint8Array(await crypto.subtle.digest("SHA-256", input));
+    }
+    finally {
+        input.fill(0);
+    }
+}
+/** The zero-access keys of the mailboxes this user has unlocked themselves - what their member wraps are addressed to. */
+function ownZeroAccessKeys() {
+    return personalSessions().flatMap(({ mailboxUid, unlocked }) => (unlocked.zeroAccessKeys ?? []).map((key) => ({ ...key, mailboxUid })));
+}
+/** Opens `wrap` with the user's own keys: the wrapped PKCS#8 (the caller zeroes it) and the own mailbox whose key opened it, or `undefined`
+ * when no own key opens it. */
+async function openWrap(wrap, own) {
+    const recipient = own.find((key) => key.fingerprint === wrap.recipientFingerprint);
+    if (!recipient) {
+        return undefined;
+    }
+    try {
+        return { pkcs8: await decryptEnvelopedDataWithKeys(fromBase64(wrap.cms), [recipient]), openedWith: recipient.mailboxUid };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The active key first, then the others newest first - the order `UnlockedKeys.zeroAccessKeys` keeps. */
+function keyOrder(status) {
+    const rank = new Map([...status.zeroAccessKeys]
+        .sort((a, b) => Number(a.fingerprint !== status.activeKeyFingerprint) - Number(b.fingerprint !== status.activeKeyFingerprint) || b.notBefore - a.notBefore)
+        .map((key, index) => [key.fingerprint, index]));
+    return (fingerprint) => rank.get(fingerprint) ?? Number.MAX_SAFE_INTEGER;
+}
+/**
+ * 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.
+ */
+export async function unlockSharedMailbox(mailboxUid, client) {
+    if (getUnlockedKeys(mailboxUid)) {
+        return "unlocked";
+    }
+    const generation = sharedUnlockGeneration(mailboxUid);
+    let status;
+    try {
+        status = await getSharedKeyStatus(mailboxUid, client);
+    }
+    catch (err) {
+        if (err instanceof ApiRequestError && (err.status === 403 || err.status === 404)) {
+            return "not_shared";
+        }
+        throw err;
+    }
+    if (status.role !== "member") {
+        return "not_shared";
+    }
+    const wraps = await getMyMemberKeyWraps(mailboxUid, client);
+    if (wraps.length === 0) {
+        return "pending";
+    }
+    const own = ownZeroAccessKeys();
+    const rank = keyOrder(status);
+    const opened = [];
+    const openedWith = new Set();
+    let secret;
+    for (const wrap of [...wraps].sort((a, b) => rank(a.zeroAccessKeyFingerprint) - rank(b.zeroAccessKeyFingerprint))) {
+        const certificate = status.zeroAccessKeys.find((key) => key.fingerprint === wrap.zeroAccessKeyFingerprint);
+        const unwrapped = certificate ? await openWrap(wrap, own) : undefined;
+        if (!certificate || !unwrapped) {
+            continue;
+        }
+        const pkcs8 = unwrapped.pkcs8;
+        try {
+            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.
+        }
+        finally {
+            pkcs8.fill(0);
+        }
+    }
+    if (!secret || opened.length === 0) {
+        return "own_keys_locked";
+    }
+    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. */
+async function openPrivateKeys(mailboxUid, status, ownerUnlocked, client) {
+    const keys = new Map();
+    if (ownerUnlocked) {
+        const vault = await getKeyVault(mailboxUid, client);
+        const aad = buildAad(mailboxUid, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE);
+        for (const key of status.zeroAccessKeys) {
+            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));
+                }
+                catch {
+                    // Sealed under a master key since replaced: not this device's to share.
+                }
+            }
+        }
+        return keys;
+    }
+    const own = ownZeroAccessKeys();
+    for (const wrap of await getMyMemberKeyWraps(mailboxUid, client)) {
+        const unwrapped = await openWrap(wrap, own);
+        if (unwrapped) {
+            keys.set(wrap.zeroAccessKeyFingerprint, unwrapped.pkcs8);
+        }
+    }
+    return keys;
+}
+async function wrapFor(member, pkcs8) {
+    return {
+        memberUserUid: member.userUid,
+        recipientFingerprint: member.certificate.fingerprint,
+        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. */
+function wrappable(status) {
+    return status.members.filter((member) => !!member.certificate);
+}
+/** `pkcs8` wrapped to the certificate of the escrow scope `escrow` describes. */
+async function escrowWrapFor(escrow, pkcs8) {
+    return { escrowScopeId: escrow.escrowScopeId, cms: toBase64(await encryptForRecipients(pkcs8, [fromBase64(escrow.publicKey.publicKey)])) };
+}
+/** A new keypair for a mailbox without an owner, enrolled together with a wrap of it for every member who can receive one, and for its
+ * escrow scope when it has one. */
+async function enrollNewSharedKey(mailboxUid, mailboxAddress, status, client) {
+    const escrow = status.escrowScopeId ? await getEscrowInfo(mailboxUid, client) : undefined;
+    const { keyPair, csrPem } = await generateKeyPairWithCsr(mailboxAddress, "encrypt");
+    const pkcs8 = await exportPrivateKeyPkcs8(keyPair.privateKey);
+    try {
+        const wraps = await Promise.all(wrappable(status).map((member) => wrapFor(member, pkcs8)));
+        const escrowWrap = escrow ? await escrowWrapFor(escrow, pkcs8) : undefined;
+        return await enrollSharedZeroAccessKey(mailboxUid, { csr: csrPem, wraps, ...(escrowWrap ? { escrowWrap } : {}) }, client);
+    }
+    finally {
+        pkcs8.fill(0);
+    }
+}
+/**
+ * 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, and the escrow scope of a mailbox without an
+ * owner gets copies of the keys it is missing (`escrowPending`).
+ */
+export async function maintainSharedMailbox(mailboxUid, mailboxAddress, client) {
+    const result = { provisioned: false, rotated: false, wrapped: 0, removed: 0, escrowed: 0 };
+    let status = await getSharedKeyStatus(mailboxUid, client);
+    if (!status.manager || (status.members.length === 0 && status.departed.length === 0)) {
+        return result;
+    }
+    const ownerUnlocked = status.role === "owner" ? getUnlockedKeys(mailboxUid) : undefined;
+    if (status.role === "owner" && (!ownerUnlocked || ownerUnlocked.shared)) {
+        return result;
+    }
+    if (status.ownerless && !status.activeKeyFingerprint) {
+        const policy = await getEncryptionPolicy(client).catch(() => undefined);
+        if (policy?.allowZeroAccess === false || ownZeroAccessKeys().length === 0) {
+            return result;
+        }
+        status = await enrollNewSharedKey(mailboxUid, mailboxAddress, status, client);
+        result.provisioned = true;
+    }
+    else if (status.rotationPending) {
+        if (status.ownerless) {
+            status = await enrollNewSharedKey(mailboxUid, mailboxAddress, status, client);
+        }
+        else {
+            const vault = await getKeyVault(mailboxUid, client);
+            await provisionZeroAccessKey(mailboxUid, mailboxAddress, ownerUnlocked.masterKey, vault.masterKeyGeneration, client);
+            status = await getSharedKeyStatus(mailboxUid, client);
+        }
+        result.rotated = true;
+    }
+    // The departed hold no wrap of the active key any more (or never did): their old wraps go.
+    if (!status.rotationPending) {
+        for (const departed of status.departed) {
+            status = await removeMemberKeyWraps(mailboxUid, departed, client);
+            result.removed++;
+        }
+    }
+    const missing = wrappable(status).filter((member) => status.zeroAccessKeys.some((key) => !member.wrapped.includes(key.fingerprint)));
+    const escrowPending = status.ownerless && status.escrowScopeId ? (status.escrowPending ?? []) : [];
+    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) {
+                    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;
+            }
+            const held = escrowPending.filter((fingerprint) => keys.has(fingerprint));
+            if (held.length > 0) {
+                const escrow = await getEscrowInfo(mailboxUid, client);
+                // Assigned to another scope since the status was read: the next pass sees it.
+                if (escrow.escrowScopeId === status.escrowScopeId) {
+                    const escrowWraps = [];
+                    for (const fingerprint of held) {
+                        escrowWraps.push({ ...(await escrowWrapFor(escrow, keys.get(fingerprint))), zeroAccessKeyFingerprint: fingerprint });
+                    }
+                    await putZeroAccessEscrowWraps(mailboxUid, escrowWraps, client);
+                    result.escrowed = escrowWraps.length;
+                }
+            }
+        }
+        finally {
+            for (const pkcs8 of keys.values()) {
+                pkcs8.fill(0);
+            }
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Zero-access keys (restapi `specs/search.md` §3): the per-mailbox keypair the server encrypts mail at rest to on arrival.
+ * Generated here like the encryption key - P-256, its certificate issued by restapi's internal CA from a CSR, its PKCS#8
+ * private key sealed under the mailbox master key - but never published: restapi keeps the certificate on
+ * `Mailbox.zeroAccessKeys` and returns it only with the vault.
+ */
+import type { ApiClient } from "../util/api.js";
+import { type KeyVault } from "./keyvaultApi.js";
+import { type RetainedEncryptionKey } from "./keySession.js";
+/** What `provisionZeroAccessKey()` resolves with. */
+export interface ProvisionedZeroAccessKey {
+    /** The vault as restapi returned it after the enrollment. */
+    vault: KeyVault;
+    /** The new key, ready to decrypt with (its private key imported non-extractable for ECDH). */
+    key: RetainedEncryptionKey;
+}
+/**
+ * Generates a zero-access keypair for `mailboxUid`, seals its private key under `masterKey` and enrolls it. The key becomes
+ * the mailbox's active zero-access key (restapi supersedes any earlier one, whose private key stays in the vault). Pass the
+ * vault's `masterKeyGeneration` read alongside `masterKey` as `expectedMasterKeyGeneration`, so restapi refuses (`409`)
+ * the key if another device rotated the master key meanwhile.
+ */
+export declare function provisionZeroAccessKey(mailboxUid: string, mailboxAddress: string, masterKey: Uint8Array, expectedMasterKeyGeneration?: number, client?: ApiClient): Promise<ProvisionedZeroAccessKey>;
+/**
+ * Gives an unlocked mailbox a zero-access key when it has none yet - how a mailbox set up before zero-access encryption
+ * existed gets one, on its owner's next unlock. Resolves `true` when it enrolled a key (and added it to the session), `false`
+ * when there was nothing to do: the mailbox isn't unlocked, or its vault already holds an unrevoked zero-access key.
+ *
+ * Only the mailbox's owner may call this (restapi refuses anybody else's enrollment); a caller decides that, e.g. from
+ * `KeyEnrollmentGate`'s `canProvision`.
+ */
+export declare function ensureZeroAccessKey(mailboxUid: string, mailboxAddress: string, client?: ApiClient): Promise<boolean>;

package/dist/lib/crypto/zeroAccessKey.js

@@ -0,0 +1,66 @@
+import { fromBase64 } from "./encoding.js";
+import { enrollKey, getKeyVault } from "./keyvaultApi.js";
+import { exportPrivateKeyPkcs8, generateKeyPairWithCsr, importPrivateKeyPkcs8 } from "./keys.js";
+import { addZeroAccessKey, getUnlockedKeys, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE } from "./keySession.js";
+import { buildAad, sealWithKey } from "./masterKey.js";
+/**
+ * Generates a zero-access keypair for `mailboxUid`, seals its private key under `masterKey` and enrolls it. The key becomes
+ * the mailbox's active zero-access key (restapi supersedes any earlier one, whose private key stays in the vault). Pass the
+ * vault's `masterKeyGeneration` read alongside `masterKey` as `expectedMasterKeyGeneration`, so restapi refuses (`409`)
+ * the key if another device rotated the master key meanwhile.
+ */
+export async function provisionZeroAccessKey(mailboxUid, mailboxAddress, masterKey, expectedMasterKeyGeneration, client) {
+    const { keyPair, csrPem } = await generateKeyPairWithCsr(mailboxAddress, "encrypt");
+    const raw = await exportPrivateKeyPkcs8(keyPair.privateKey);
+    try {
+        const sealed = await sealWithKey(masterKey, raw, buildAad(mailboxUid, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE));
+        const vault = await enrollKey(mailboxUid, {
+            useType: "zero-access",
+            csr: csrPem,
+            wrappedKey: { ciphertext: sealed.ciphertext, nonce: sealed.nonce, algorithm: "AES-256-GCM" },
+            ...(expectedMasterKeyGeneration !== undefined ? { expectedMasterKeyGeneration } : {}),
+        }, client);
+        // restapi appends the new wrapped key last.
+        const enrolled = [...vault.wrappedKeys].reverse().find((k) => k.useType === "zero-access");
+        const certificate = enrolled && vault.zeroAccessKeys?.find((k) => k.fingerprint === enrolled.fingerprint);
+        if (!enrolled || !certificate) {
+            throw new Error("The server did not return the enrolled zero-access key.");
+        }
+        const privateKey = await importPrivateKeyPkcs8(raw, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"], false);
+        return { vault, key: { fingerprint: enrolled.fingerprint, certDer: fromBase64(certificate.publicKey), privateKey } };
+    }
+    finally {
+        raw.fill(0);
+    }
+}
+/** Provisions already in flight, per mailbox - a second caller (another effect, a re-render) joins the first. */
+const inFlight = new Map();
+/**
+ * Gives an unlocked mailbox a zero-access key when it has none yet - how a mailbox set up before zero-access encryption
+ * existed gets one, on its owner's next unlock. Resolves `true` when it enrolled a key (and added it to the session), `false`
+ * when there was nothing to do: the mailbox isn't unlocked, or its vault already holds an unrevoked zero-access key.
+ *
+ * Only the mailbox's owner may call this (restapi refuses anybody else's enrollment); a caller decides that, e.g. from
+ * `KeyEnrollmentGate`'s `canProvision`.
+ */
+export function ensureZeroAccessKey(mailboxUid, mailboxAddress, client) {
+    const pending = inFlight.get(mailboxUid);
+    if (pending) {
+        return pending;
+    }
+    const run = (async () => {
+        const unlocked = getUnlockedKeys(mailboxUid);
+        if (!unlocked || unlocked.zeroAccessKeys?.length) {
+            return false;
+        }
+        const vault = await getKeyVault(mailboxUid, client);
+        if ((vault.zeroAccessKeys ?? []).some((k) => !k.revokedAt) || vault.wrappedKeys.length === 0) {
+            return false;
+        }
+        const { key } = await provisionZeroAccessKey(mailboxUid, mailboxAddress, unlocked.masterKey, vault.masterKeyGeneration, client);
+        addZeroAccessKey(mailboxUid, unlocked, key);
+        return true;
+    })().finally(() => inFlight.delete(mailboxUid));
+    inFlight.set(mailboxUid, run);
+    return run;
+}

package/dist/lib/mail/conversationsApi.d.ts

@@ -31,6 +31,12 @@ export interface ConversationSummary {
     latestFrom: Recipient;
     /** The most recent message's `bodyPreview` — the snippet a collapsed row shows. */
     latestPreview: string;
+    /** Set when the latest message is sealed at rest (zero-access): its subject and preview are only in `sealedSummary`, which
+     * `messageSecurity.ts`'s `openZeroAccessSummary()` opens with the mailbox's zero-access keys. */
+    latestZeroAccess?: {
+        keyFingerprint: string;
+        sealedSummary: string;
+    };
     /** The most recent message's folder. */
     latestFolderUid: string;
     /** The iTIP `METHOD` of the calendar file the most recent message carries (`Message.meetingMethod`) - `"REQUEST"`, `"REPLY"`,