@rapidmx/web-client 0.35.0 → 0.36.0

package/lib/crypto/sharedMailboxKeys.ts

@@ -0,0 +1,324 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { type ApiClient, ApiRequestError } from "../util/api.js";
+import { fromBase64, toBase64 } from "./encoding.js";
+import {
+    enrollSharedZeroAccessKey,
+    type EscrowInfo,
+    getEncryptionPolicy,
+    getEscrowInfo,
+    getKeyVault,
+    getMyMemberKeyWraps,
+    getSharedKeyStatus,
+    type MemberKeyWrap,
+    putMemberKeyWraps,
+    putZeroAccessEscrowWraps,
+    removeMemberKeyWraps,
+    type SharedKeyStatus,
+    type ZeroAccessEscrowWrapInput,
+    type ZeroAccessKey,
+} from "./keyvaultApi.js";
+import { exportPrivateKeyPkcs8, generateKeyPairWithCsr, importPrivateKeyPkcs8 } from "./keys.js";
+import {
+    getUnlockedKeys,
+    installSharedSession,
+    personalSessions,
+    type RetainedEncryptionKey,
+    sharedUnlockGeneration,
+    type UnlockedKeys,
+    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";
+
+/** 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";
+
+/** 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: Uint8Array): Promise<Uint8Array> {
+    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);
+    }
+}
+
+/** One of the user's own zero-access keys, with the mailbox it belongs to. */
+type OwnKey = RetainedEncryptionKey & { mailboxUid: string };
+
+/** The zero-access keys of the mailboxes this user has unlocked themselves - what their member wraps are addressed to. */
+function ownZeroAccessKeys(): OwnKey[] {
+    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: MemberKeyWrap, own: OwnKey[]): Promise<{ pkcs8: Uint8Array; openedWith: string } | undefined> {
+    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: Pick<SharedKeyStatus, "activeKeyFingerprint" | "zeroAccessKeys">): (fingerprint: string) => number {
+    const rank = new Map<string, number>(
+        [...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: string, client?: ApiClient): Promise<SharedUnlockOutcome> {
+    if (getUnlockedKeys(mailboxUid)) {
+        return "unlocked";
+    }
+    const generation: string = sharedUnlockGeneration(mailboxUid);
+    let status: SharedKeyStatus;
+    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: MemberKeyWrap[] = await getMyMemberKeyWraps(mailboxUid, client);
+    if (wraps.length === 0) {
+        return "pending";
+    }
+    const own = ownZeroAccessKeys();
+    const rank = keyOrder(status);
+    const opened: RetainedEncryptionKey[] = [];
+    const openedWith: Set<string> = new Set();
+    let secret: Uint8Array | undefined;
+    for (const wrap of [...wraps].sort((a, b) => rank(a.zeroAccessKeyFingerprint) - rank(b.zeroAccessKeyFingerprint))) {
+        const certificate: ZeroAccessKey | undefined = 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 ??= 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: UnlockedKeys = { 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: string,
+    status: SharedKeyStatus,
+    ownerUnlocked: UnlockedKeys | undefined,
+    client?: ApiClient,
+): Promise<Map<string, Uint8Array>> {
+    const keys = new Map<string, Uint8Array>();
+    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: { userUid: string; certificate: ZeroAccessKey }, pkcs8: Uint8Array): Promise<Omit<MemberKeyWrap, "zeroAccessKeyFingerprint">> {
+    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: SharedKeyStatus): { userUid: string; certificate: ZeroAccessKey; wrapped: string[] }[] {
+    return status.members.filter((member): member is typeof member & { certificate: ZeroAccessKey } => !!member.certificate);
+}
+
+/** `pkcs8` wrapped to the certificate of the escrow scope `escrow` describes. */
+async function escrowWrapFor(escrow: EscrowInfo, pkcs8: Uint8Array): Promise<Omit<ZeroAccessEscrowWrapInput, "zeroAccessKeyFingerprint">> {
+    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: string, mailboxAddress: string, status: SharedKeyStatus, client?: ApiClient): Promise<SharedKeyStatus> {
+    const escrow: EscrowInfo | undefined = 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);
+    }
+}
+
+/** 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 async function maintainSharedMailbox(mailboxUid: string, mailboxAddress: string, client?: ApiClient): Promise<SharedMaintenance> {
+    const result: SharedMaintenance = { provisioned: false, rotated: false, wrapped: 0, removed: 0, escrowed: 0 };
+    let status: SharedKeyStatus = 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: string[] = status.ownerless && status.escrowScopeId ? (status.escrowPending ?? []) : [];
+    if (missing.length > 0 || escrowPending.length > 0) {
+        const keys = await openPrivateKeys(mailboxUid, status, ownerUnlocked, client);
+        try {
+            const wraps: MemberKeyWrap[] = [];
+            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: string[] = escrowPending.filter((fingerprint) => keys.has(fingerprint));
+            if (held.length > 0) {
+                const escrow: EscrowInfo = 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: ZeroAccessEscrowWrapInput[] = [];
+                    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/lib/crypto/zeroAccessKey.ts

@@ -0,0 +1,97 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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 { fromBase64 } from "./encoding.js";
+import { type KeyVault, enrollKey, getKeyVault } from "./keyvaultApi.js";
+import { exportPrivateKeyPkcs8, generateKeyPairWithCsr, importPrivateKeyPkcs8 } from "./keys.js";
+import { addZeroAccessKey, getUnlockedKeys, type RetainedEncryptionKey, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE } from "./keySession.js";
+import { buildAad, sealWithKey } from "./masterKey.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 async function provisionZeroAccessKey(
+    mailboxUid: string,
+    mailboxAddress: string,
+    masterKey: Uint8Array,
+    expectedMasterKeyGeneration?: number,
+    client?: ApiClient,
+): Promise<ProvisionedZeroAccessKey> {
+    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<string, Promise<boolean>>();
+
+/**
+ * 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: string, mailboxAddress: string, client?: ApiClient): Promise<boolean> {
+    const pending = inFlight.get(mailboxUid);
+    if (pending) {
+        return pending;
+    }
+    const run = (async (): Promise<boolean> => {
+        const unlocked = getUnlockedKeys(mailboxUid);
+        if (!unlocked || unlocked.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/lib/mail/conversationsApi.ts

@@ -37,6 +37,9 @@ 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"`,

package/lib/mail/mailApi.ts

@@ -26,7 +26,7 @@ import {
 } from "../util/api.js";
 import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 import { deviceTimeZone } from "../util/timeZone.js";
-import type { EncryptionPreference, PublicKey } from "../crypto/keyvaultApi.js";
+import type { EncryptionPreference, PublicKey, ZeroAccessKey } from "../crypto/keyvaultApi.js";
 import { bytesToBinaryString } from "../crypto/mime.js";
 import { EMBEDDED_IMAGE_TYPES, newContentId, parseDataImage } from "./inlineImages.js";
 import { MAX_QUOTED_IMAGE_BYTES } from "./compose/quotedImages.js";
@@ -129,6 +129,12 @@ export interface Mailbox {
      * per the spec's own `PublicKey` doc comment. Absent/empty means no keys enrolled yet
      * (`KeyEnrollmentGate` handles that state). */
     keys?: PublicKey[];
+    /** The mailbox's zero-access certificates, managed by the server (never written by a client). Read them from
+     * `KeyVault.zeroAccessKeys` to unlock; here only so a settings page can tell whether one is enrolled. */
+    zeroAccessKeys?: ZeroAccessKey[];
+    /** "Enable zero-access encryption": unset means on. Only the mailbox's owner can change it - restapi drops anybody
+     * else's value. Has no effect while the server's `EncryptionPolicy.allowZeroAccess` is off. */
+    zeroAccessEnabled?: boolean;
     /** How the caller reaches this mailbox: `"owner"` (theirs) or `"delegate"` (shared with them). Set by the plain list and read of
      * mailboxes - not in an administration-scope answer - so a client can label the shared ones; see `isSharedWithMe()`. */
     accessRole?: "owner" | "delegate";
@@ -281,6 +287,8 @@ export interface UpdateMailboxInput {
     autoSendReceiptsInternal?: boolean;
     autoSendReceiptsFederated?: boolean;
     autoSendReceiptsExternal?: boolean;
+    /** Owner-only server-side (anybody else's value is dropped) - see `Mailbox.zeroAccessEnabled`. */
+    zeroAccessEnabled?: boolean;
     /** Trusted-caller-only server-side. `null` (or `""`) unassigns the mailbox's escrow scope; the
      * referenced `EscrowScope` must exist otherwise. See `Mailbox.escrowScopeId`. */
     escrowScopeId?: string | null;
@@ -594,6 +602,10 @@ export interface Message {
      * stored body, not from a flag this API exposes. Always present on a real `Message` (defaults
      * `false` server-side), same optional-for-old-fixtures caveat as `Mailbox.oofEnabled`. */
     encrypted?: boolean;
+    /** Set when the server sealed this message at rest on arrival (zero-access, restapi `specs/search.md` §3): its stored body is an
+     * S/MIME message only the mailbox's zero-access key opens, `subject` is `[...]` and `bodyPreview` empty - the real ones are in
+     * `sealedSummary`. */
+    zeroAccess?: { keyFingerprint: string; sealedSummary: string };
     /** The raw RFC 2369/8058 `List-Unsubscribe` header value, if present — computed server-side by
      * `@rapidmx/restapi`'s `ScanPipeline` from the stored MIME, the strongest single bulk-mail signal it
      * captures. Used client-side to detect list traffic when replying, per
@@ -797,7 +809,7 @@ export type MessageReportKind = "junk" | "phishing" | "not_junk";
 /** Why the server did not teach its spam filter from a report: `encrypted` (it has no plaintext to teach), `disabled` (learning is switched off),
  * `unsupported` (no spam engine, or one that cannot learn), `too_large` (over the size it reads) or `failed` (the engine could not be reached,
  * refused, or the message could not be read). The report itself still happened. */
-export type MessageLearnSkipped = "encrypted" | "disabled" | "unsupported" | "too_large" | "failed";
+export type MessageLearnSkipped = "encrypted" | "zero_access" | "disabled" | "unsupported" | "too_large" | "failed";
 
 /** What `reportMessage()` answers. */
 export interface MessageReportResult {
@@ -820,6 +832,9 @@ export interface ReportMessageOptions {
     /** With `not_junk` only (else a 400): also add the message's From address to the mailbox's safe senders. Needs full access to the mailbox (403 otherwise,
      * before anything is done). */
     alwaysTrustSender?: boolean;
+    /** For a zero-access message only (else a 400): its original source, base64-encoded, decrypted here - the server holds only the sealed
+     * copy, so this is what its spam filter learns from (never stored). Without it the server skips learning (`learnSkipped: "zero_access"`). */
+    rawMessage?: string;
 }
 
 /**
@@ -837,7 +852,11 @@ export function reportMessage(
 ): Promise<MessageReportResult> {
     return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/report`, {
         method: "POST",
-        body: JSON.stringify({ kind, ...(options.alwaysTrustSender ? { alwaysTrustSender: true } : {}) }),
+        body: JSON.stringify({
+            kind,
+            ...(options.alwaysTrustSender ? { alwaysTrustSender: true } : {}),
+            ...(options.rawMessage ? { rawMessage: options.rawMessage } : {}),
+        }),
     });
 }
 
@@ -1073,8 +1092,17 @@ export interface AssembleDraftInput {
     bcc?: ComposeRecipientInput[];
     subject?: string;
     html: string;
+    /** See `AssembleIntent`. */
+    intent?: AssembleIntent;
 }
 
+/**
+ * Why a draft is being assembled (server `ComposeIntent`). `"save"`, the default, keeps an edit: in a zero-access mailbox the server
+ * stores it sealed, which it can't send. `"send"` is the assemble right before `sendMessage()`/`queueMessageSend()`: stored readable
+ * until it is relayed, then sealed as the Sent Items copy.
+ */
+export type AssembleIntent = "save" | "send";
+
 /** What a draft records about the thread it belongs to - see `createDraft()`. */
 export interface DraftThreading {
     /** The `messageId` of the message being replied to (`Message.inReplyTo`). */
@@ -1266,6 +1294,8 @@ export interface AssembleDraftRawInput {
      * `crypto/smimeMessage.ts`'s `buildSignedOnlyMessage()`/`buildEncryptedMessage()`, combined with
      * the outer envelope headers (`From`/`To`/`Cc`/`Date`/`Message-ID`/`MIME-Version`) by the caller. */
     rawMime: string;
+    /** See `AssembleIntent`. */
+    intent?: AssembleIntent;
 }
 
 /**

package/lib/search/zeroAccessIndexApi.ts

@@ -0,0 +1,119 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s zero-access search index (`/mail/mailboxes/:id/search-index`, `specs/search.md` §7-8): the
+ * sealed index entries the server writes at delivery and the weekly segments clients compact them into. Everything here is
+ * ciphertext encrypted to the mailbox's zero-access key - `apps/shared/search/zeroAccessIndexSync.ts` decrypts and imports it.
+ */
+import { type ApiClient, withClient, withClientBlob } from "../util/api.js";
+
+export type SegmentOrigin = "zero-access" | "client";
+
+/** A compacted segment as the manifest lists it. */
+export interface IndexSegment {
+    weekId: string;
+    generation: number;
+    origin: SegmentOrigin;
+    bytes: number;
+    etag: string;
+    schemaVersion: number;
+    keyFingerprint: string;
+    entryCount: number;
+}
+
+/** A week's entries not yet compacted. */
+export interface IndexWeekEntries {
+    weekId: string;
+    pendingEntries: number;
+    latestEntryAt: string;
+    /** The week has closed and its grace period has passed: a client may compact it. */
+    compactable: boolean;
+}
+
+export interface SegmentManifest {
+    mailboxUid: string;
+    segments: IndexSegment[];
+    weeks: IndexWeekEntries[];
+}
+
+/** One pending entry: `sealed` is base64 CMS `EnvelopedData` of a gzipped JSON `ZeroAccessIndexDocument`. */
+export interface SealedIndexEntry {
+    uid: string;
+    weekId: string;
+    messageUid: string;
+    createdAt: string;
+    keyFingerprint: string;
+    sealed: string;
+}
+
+export interface SealedIndexEntryPage {
+    entries: SealedIndexEntry[];
+    next?: string;
+}
+
+/** What a sealed entry (and each document of a segment) decrypts to - restapi's `ZeroAccessIndexDocument`. */
+export interface ZeroAccessIndexDocument {
+    v: 1;
+    messageUid: string;
+    subject: string;
+    body: string;
+    attachmentText: string[];
+    attachmentNames: string[];
+    deferredAttachments: string[];
+    from: string;
+    to: string[];
+    cc: string[];
+    participants: string[];
+    dateForSort: number;
+}
+
+/** `PUT .../segments/:weekId`. */
+export interface SegmentUpload {
+    expectedGeneration: number;
+    /** Base64 of the sealed file. */
+    segment: string;
+    keyFingerprint: string;
+    schemaVersion: number;
+    origin?: SegmentOrigin;
+    foldedEntryUids?: string[];
+}
+
+const base = (mailboxUid: string): string => `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/search-index`;
+
+export function getSearchIndexManifest(mailboxUid: string, client?: ApiClient): Promise<SegmentManifest> {
+    return withClient(client, `${base(mailboxUid)}/manifest`);
+}
+
+/** One page of pending entries: of `week` when given, written at or after `since` when given, after uid `after`. */
+export function listSearchIndexEntries(
+    mailboxUid: string,
+    options: { week?: string; since?: string; after?: string; limit?: number } = {},
+    client?: ApiClient,
+): Promise<SealedIndexEntryPage> {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined) {
+            query.set(key, String(value));
+        }
+    }
+    const search = query.toString();
+    return withClient(client, `${base(mailboxUid)}/entries${search ? `?${search}` : ""}`);
+}
+
+/** The sealed file of a week's segment generation. */
+export async function getSearchIndexSegment(
+    mailboxUid: string,
+    segment: Pick<IndexSegment, "weekId" | "generation" | "origin">,
+    client?: ApiClient,
+): Promise<Uint8Array> {
+    const query = `generation=${segment.generation}${segment.origin === "client" ? "&origin=client" : ""}`;
+    const blob = await withClientBlob(client, `${base(mailboxUid)}/segments/${encodeURIComponent(segment.weekId)}?${query}`, "Could not download a search index segment.");
+    return new Uint8Array(await blob.arrayBuffer());
+}
+
+/** Stores a compaction. Rejects with a `409` when the week's segment changed since `upload.expectedGeneration` was read. */
+export function putSearchIndexSegment(mailboxUid: string, weekId: string, upload: SegmentUpload, client?: ApiClient): Promise<IndexSegment> {
+    return withClient(client, `${base(mailboxUid)}/segments/${encodeURIComponent(weekId)}`, { method: "PUT", body: JSON.stringify(upload) });
+}