@rapidmx/web-client 0.35.0 → 0.36.0

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

@@ -10,7 +10,7 @@
  */
 import { ApiClient, ApiRequestError } from "../util/api.js";
 import { ListParams } from "../util/apiQuery.js";
-import type { EncryptionPreference, PublicKey } from "../crypto/keyvaultApi.js";
+import type { EncryptionPreference, PublicKey, ZeroAccessKey } from "../crypto/keyvaultApi.js";
 import type { ResolvedPrincipal } from "./mailboxAccessApi.js";
 export type { ListParams };
 export type { EncryptionPreference, PublicKey };
@@ -95,6 +95,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";
@@ -215,6 +221,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;
@@ -424,6 +432,13 @@ 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
@@ -560,7 +575,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 {
     uid: string;
@@ -581,6 +596,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;
 }
 /**
  * Reports a message as junk, phishing or not junk - `POST /mail/messages/:uid/report`. The SERVER moves it (`junk` and `phishing` to the mailbox's Junk Email,
@@ -708,7 +726,15 @@ 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`). */
@@ -774,6 +800,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;
 }
 /**
  * Stores an already-signed/encrypted draft's raw MIME source as its `bodyBlobKey`, completely

package/dist/lib/mail/mailApi.js

@@ -274,7 +274,11 @@ export function moveMessage(message, folderUid, client) {
 export function reportMessage(uid, kind, options = {}, client) {
     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 } : {}),
+        }),
     });
 }
 /**

package/dist/lib/search/zeroAccessIndexApi.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 } 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[];
+}
+export declare function getSearchIndexManifest(mailboxUid: string, client?: ApiClient): Promise<SegmentManifest>;
+/** One page of pending entries: of `week` when given, written at or after `since` when given, after uid `after`. */
+export declare function listSearchIndexEntries(mailboxUid: string, options?: {
+    week?: string;
+    since?: string;
+    after?: string;
+    limit?: number;
+}, client?: ApiClient): Promise<SealedIndexEntryPage>;
+/** The sealed file of a week's segment generation. */
+export declare function getSearchIndexSegment(mailboxUid: string, segment: Pick<IndexSegment, "weekId" | "generation" | "origin">, client?: ApiClient): Promise<Uint8Array>;
+/** Stores a compaction. Rejects with a `409` when the week's segment changed since `upload.expectedGeneration` was read. */
+export declare function putSearchIndexSegment(mailboxUid: string, weekId: string, upload: SegmentUpload, client?: ApiClient): Promise<IndexSegment>;

package/dist/lib/search/zeroAccessIndexApi.js

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { withClient, withClientBlob } from "../util/api.js";
+const base = (mailboxUid) => `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/search-index`;
+export function getSearchIndexManifest(mailboxUid, client) {
+    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, options = {}, client) {
+    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, segment, client) {
+    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, weekId, upload, client) {
+    return withClient(client, `${base(mailboxUid)}/segments/${encodeURIComponent(weekId)}`, { method: "PUT", body: JSON.stringify(upload) });
+}

package/lib/admin/escrowAccessRequestsApi.ts

@@ -14,6 +14,7 @@
 
 import { ApiClient, withClient } from "../util/api.js";
 import { ListParams, RequestListParams, buildQuery } from "../util/apiQuery.js";
+import type { PublicKey, WrappedPrivateKey } from "../crypto/keyvaultApi.js";
 
 export type { ListParams, RequestListParams };
 
@@ -65,6 +66,11 @@ export interface MasterKeyWrap {
  * tooling, per `specs/end-to-end_encryption.md`'s "this server never holds the scope's private key". */
 export interface EscrowAccessMaterial {
     masterKeyWraps: MasterKeyWrap[];
+    /** The mailbox's wrapped private keys that read mail (zero-access and encryption keys, never signing), sealed under its master key. Absent
+     * from a server that predates releasing them. */
+    wrappedKeys?: WrappedPrivateKey[];
+    /** The certificate of each of `wrappedKeys`, matched by fingerprint. */
+    certificates?: PublicKey[];
 }
 
 /** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one

package/lib/calendar/calendarApi.ts

@@ -135,6 +135,9 @@ export interface CalendarEvent {
      * `mailto` only). Still to be rendered through `sanitizeEventDescriptionHtml()` (`eventDescription.ts`), never trusted as it stands. `null` or absent:
      * the description, if any, is plain text. */
     descriptionHtml?: string | null;
+    /** Response-only. An event made from an invitation that reached a zero-access mailbox: its title, location and description are only
+     * sealed to the mailbox's zero-access key (`title` is `[...]`). `apps/shared/calendar/sealedEvents.ts` opens them. */
+    sealedContent?: { keyFingerprint: string; sealed: string };
     /** Who may see the event's details - absent (or `null`, on a row stored before this existed) reads as `"default"`; see `visibilityOf()`. */
     visibility?: EventVisibility | null;
     /** Whether the guests may ask for the event to change (default `false`). Absent or `null` reads as the default; see `guestPermissionsOf()`. */

package/lib/calendar/inviteApi.ts

@@ -10,6 +10,14 @@
 
 import { ApiClient, ApiRequestError, withClient } from "../util/api.js";
 import type { EventVisibility, GuestPermissions } from "./calendarApi.js";
+import { sealedInviteCalendar } from "./sealedInvites.js";
+
+/** The calendar file to send for `messageUid` - a zero-access message this device decrypted (`sealedInvites.ts`) - as the request body's
+ * `ics`, or nothing for a message the server reads itself. */
+function sealedSource(messageUid: string): { ics?: string } {
+    const ics = sealedInviteCalendar(messageUid);
+    return ics !== undefined ? { ics } : {};
+}
 
 /** What the reader can answer an invitation with. */
 export type InviteResponse = "accepted" | "tentative" | "declined";
@@ -104,8 +112,15 @@ export interface MessageInvite {
  * common, expected answer for a message that merely has an attachment - and rejects for any other failure.
  */
 export async function getMessageInvite(messageUid: string, client?: ApiClient): Promise<MessageInvite | null> {
+    const source = sealedSource(messageUid);
     try {
-        return await withClient<MessageInvite>(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}`);
+        // A zero-access message's invitation is read from the calendar file decrypted here (`POST .../view`).
+        return source.ics !== undefined
+            ? await withClient<MessageInvite>(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/view`, {
+                  method: "POST",
+                  body: JSON.stringify(source),
+              })
+            : await withClient<MessageInvite>(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}`);
     } catch (err) {
         if (err instanceof ApiRequestError && err.status === 404) {
             return null;
@@ -122,13 +137,17 @@ export async function getMessageInvite(messageUid: string, client?: ApiClient):
 export function respondToMessageInvite(messageUid: string, responseStatus: InviteResponse, client?: ApiClient): Promise<MessageInvite> {
     return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/respond`, {
         method: "POST",
-        body: JSON.stringify({ responseStatus }),
+        body: JSON.stringify({ responseStatus, ...sealedSource(messageUid) }),
     });
 }
 
 /** Takes a canceled meeting off the reader's calendar. Resolves with the invitation as it now stands. */
 export function removeMessageInvite(messageUid: string, client?: ApiClient): Promise<MessageInvite> {
-    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/remove`, { method: "POST" });
+    const source = sealedSource(messageUid);
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/remove`, {
+        method: "POST",
+        ...(source.ics !== undefined ? { body: JSON.stringify(source) } : {}),
+    });
 }
 
 /** A different time to suggest to the organizer. */
@@ -144,11 +163,15 @@ export interface ProposedTime {
 export function proposeNewTime(messageUid: string, proposal: ProposedTime, client?: ApiClient): Promise<MessageInvite> {
     return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/propose`, {
         method: "POST",
-        body: JSON.stringify(proposal),
+        body: JSON.stringify({ ...proposal, ...sealedSource(messageUid) }),
     });
 }
 
 /** Accepts an attendee's proposed time (a `COUNTER`) for a meeting the reader organizes: the server moves the event and sends the attendees the update. Resolves with the invitation as it now stands. */
 export function acceptProposal(messageUid: string, client?: ApiClient): Promise<MessageInvite> {
-    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/accept-proposal`, { method: "POST" });
+    const source = sealedSource(messageUid);
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/accept-proposal`, {
+        method: "POST",
+        ...(source.ics !== undefined ? { body: JSON.stringify(source) } : {}),
+    });
 }

package/lib/calendar/sealedInvites.ts

@@ -0,0 +1,33 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The calendar files of zero-access messages, as decrypted on this device (`MessageSecurityResult.calendar`). The server holds only
+ * the sealed copy of such a message, so every invitation call for it (`inviteApi.ts`) sends the file along. Kept in memory for the
+ * messages read most recently, and cleared on sign-out (`clearSealedInvites()`).
+ */
+
+/** How many messages' calendar files are kept. */
+const MAX_SEALED_INVITES = 100;
+
+const calendars: Map<string, string> = new Map();
+
+/** Remembers the decrypted calendar file of zero-access message `messageUid`. */
+export function rememberSealedInvite(messageUid: string, ics: string): void {
+    calendars.delete(messageUid);
+    calendars.set(messageUid, ics);
+    while (calendars.size > MAX_SEALED_INVITES) {
+        calendars.delete(calendars.keys().next().value!);
+    }
+}
+
+/** The decrypted calendar file of zero-access message `messageUid`, when this device has read it. */
+export function sealedInviteCalendar(messageUid: string): string | undefined {
+    return calendars.get(messageUid);
+}
+
+/** Forgets every remembered calendar file (sign-out). */
+export function clearSealedInvites(): void {
+    calendars.clear();
+}

package/lib/crypto/keyExport.ts

@@ -0,0 +1,229 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * "Export keys for Outlook/phone" (restapi `specs/search.md` §3, *Clients that don't run RapidMX*): a passphrase-protected
+ * PKCS#12 file holding the private keys a mail client needs to read this mailbox's mail on its own - every zero-access key
+ * (mail at rest is S/MIME `enveloped-data` to these) and every end-to-end encryption key (current and retained), plus, only
+ * when asked, the active signing key. Built entirely here from a fresh master-password unlock: the session's own private
+ * keys are non-extractable, and the server never sees the file or the passphrase. restapi only records that an export
+ * happened (`key_vault.export`), with the fingerprints exported and nothing else.
+ */
+import "reflect-metadata";
+import * as asn1js from "asn1js";
+import * as pkijs from "pkijs";
+import type { ApiClient } from "../util/api.js";
+import { fromBase64 } from "./encoding.js";
+import { type KeyVault, type PublicKey, findActivePublicKey, recordKeyExport, type WrappedPrivateKey } from "./keyvaultApi.js";
+import {
+    ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE,
+    MAX_RETAINED_ENCRYPTION_KEYS,
+    openMasterKeyWithPassword,
+    SIGNING_PRIVATE_KEY_AAD_PURPOSE,
+    ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE,
+} from "./keySession.js";
+import { buildAad, openWithKey } from "./masterKey.js";
+
+/** PBKDF2 iterations for the shrouded key bags and the PKCS#12 MAC. Windows, macOS and iOS all accept this. */
+export const KEY_EXPORT_ITERATIONS = 100_000;
+
+/** The shortest export passphrase accepted. The file grants read access to all of this mailbox's mail. */
+export const MIN_EXPORT_PASSPHRASE_LENGTH = 12;
+
+const PKCS8_SHROUDED_KEY_BAG = "1.2.840.113549.1.12.10.1.2";
+const CERT_BAG = "1.2.840.113549.1.12.10.1.3";
+const X509_CERTIFICATE = "1.2.840.113549.1.9.22.1";
+const FRIENDLY_NAME = "1.2.840.113549.1.9.20";
+const LOCAL_KEY_ID = "1.2.840.113549.1.9.21";
+
+/** The shrouded key bags' cipher. pkijs's type wants an `iv`, but it generates a fresh one for every bag and ignores this one. */
+const AES_256_CBC = { name: "AES-CBC", length: 256, iv: new Uint8Array(16) } as pkijs.ContentEncryptionAlgorithm;
+
+/** Which key a bag holds, for its friendly name and the export's audit record. */
+export type ExportedKeyKind = "zero-access" | "encrypt" | "sign";
+
+/** What `exportKeysAsPkcs12()` takes. */
+export interface KeyExportInput {
+    mailboxUid: string;
+    /** The mailbox's address, used in each key's friendly name. */
+    mailboxAddress: string;
+    /** The mailbox's published keys (`Mailbox.keys`): the encryption and signing certificates. */
+    mailboxKeys: PublicKey[];
+    /** The master password, for the fresh unlock every export needs. */
+    masterPassword: string;
+    /** Protects the PKCS#12 file. At least `MIN_EXPORT_PASSPHRASE_LENGTH` characters. */
+    exportPassphrase: string;
+    /** Whether to include the active signing key, for clients that will sign. Off unless the user opts in. */
+    includeSigningKey?: boolean;
+}
+
+/** One key in the export. */
+export interface ExportedKey {
+    kind: ExportedKeyKind;
+    fingerprint: string;
+}
+
+/** What `exportKeysAsPkcs12()` resolves with. */
+export interface KeyExport {
+    /** The DER-encoded PKCS#12 (`.p12`) file. */
+    pkcs12: Uint8Array;
+    /** The keys it holds, zero-access keys first. */
+    keys: ExportedKey[];
+}
+
+/** One private key opened from the vault, before it goes into a bag. Its `pkcs8` is zeroed once the file is built. */
+interface OpenedKey extends ExportedKey {
+    certDer: Uint8Array;
+    pkcs8: Uint8Array;
+}
+
+/** The export has nothing to hold - the vault has no zero-access or encryption private key this password opens. */
+export class NothingToExportError extends Error {
+    constructor() {
+        super("This mailbox has no keys to export yet.");
+        this.name = "NothingToExportError";
+    }
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+function hexBytes(hex: string): Uint8Array {
+    const out = new Uint8Array(hex.length >> 1);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+
+function bagAttributes(friendlyName: string, localKeyId: Uint8Array): pkijs.Attribute[] {
+    return [
+        new pkijs.Attribute({ type: FRIENDLY_NAME, values: [new asn1js.BmpString({ value: friendlyName })] }),
+        new pkijs.Attribute({ type: LOCAL_KEY_ID, values: [new asn1js.OctetString({ valueHex: toArrayBuffer(localKeyId) })] }),
+    ];
+}
+
+function friendlyName(kind: ExportedKeyKind, address: string, index: number): string {
+    const label = kind === "zero-access" ? "zero-access key" : kind === "encrypt" ? "encryption key" : "signing key";
+    return `RapidMX ${label} (${address})${index > 0 ? ` ${index + 1}` : ""}`;
+}
+
+/** Opens one wrapped private key to its raw PKCS#8, or `undefined` when it won't open under this master key - an export
+ * carries what it can rather than failing on one stale wrap. */
+async function openPkcs8(masterKey: Uint8Array, wrapped: WrappedPrivateKey, aad: Uint8Array): Promise<Uint8Array | undefined> {
+    try {
+        return await openWithKey(masterKey, wrapped, aad);
+    } catch {
+        return undefined;
+    }
+}
+
+/** Opens every key the export holds, in order: zero-access keys (unrevoked newest first), the encryption keys (active
+ * first, then retained newest first), then the active signing key if asked. Each list is capped like the session's. */
+async function openExportedKeys(input: KeyExportInput, vault: KeyVault, masterKey: Uint8Array): Promise<OpenedKey[]> {
+    const opened: OpenedKey[] = [];
+    const wrappedFor = (fingerprint: string) => vault.wrappedKeys.find((k) => k.fingerprint === fingerprint);
+    const take = async (kind: ExportedKeyKind, keys: { fingerprint: string; publicKey: string }[], purpose: string, max: number) => {
+        const aad = buildAad(input.mailboxUid, purpose);
+        const seen = new Set<string>();
+        for (const key of keys) {
+            const wrapped = wrappedFor(key.fingerprint);
+            if (!wrapped || seen.has(key.fingerprint) || seen.size === max) {
+                continue;
+            }
+            const pkcs8 = await openPkcs8(masterKey, wrapped, aad);
+            if (pkcs8) {
+                seen.add(key.fingerprint);
+                opened.push({ kind, fingerprint: key.fingerprint, certDer: fromBase64(key.publicKey), pkcs8 });
+            }
+        }
+    };
+
+    const zeroAccess = [...(vault.zeroAccessKeys ?? [])].sort((a, b) => Number(!!a.revokedAt) - Number(!!b.revokedAt) || b.notBefore - a.notBefore);
+    await take("zero-access", zeroAccess, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE, MAX_RETAINED_ENCRYPTION_KEYS + 1);
+
+    const active = findActivePublicKey(input.mailboxKeys, "encrypt");
+    const encryption = [
+        ...(active ? [active] : []),
+        ...input.mailboxKeys.filter((k) => k.useType === "encrypt" && k !== active).sort((a, b) => b.notBefore - a.notBefore),
+    ];
+    await take("encrypt", encryption, ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE, MAX_RETAINED_ENCRYPTION_KEYS + 1);
+
+    if (input.includeSigningKey) {
+        const signing = findActivePublicKey(input.mailboxKeys, "sign");
+        await take("sign", signing ? [signing] : [], SIGNING_PRIVATE_KEY_AAD_PURPOSE, 1);
+    }
+    return opened;
+}
+
+/** Builds the PKCS#12 file: one PBES2 (PBKDF2-SHA256, AES-256-CBC) shrouded key bag and one certificate bag per key,
+ * paired by `localKeyID`, in an unencrypted SafeContents, under a SHA-256 MAC. */
+async function buildPkcs12(keys: OpenedKey[], address: string, passphrase: string): Promise<Uint8Array> {
+    const crypto = pkijs.getCrypto(true);
+    // UTF-8 for both: pkijs re-encodes it as the BMPString the PKCS#12 MAC derivation (RFC 7292 Appendix B) takes.
+    const utf8 = toArrayBuffer(new TextEncoder().encode(passphrase));
+    const bags: pkijs.SafeBag[] = [];
+    const shrouded: pkijs.PKCS8ShroudedKeyBag[] = [];
+    const counts: Record<ExportedKeyKind, number> = { "zero-access": 0, encrypt: 0, sign: 0 };
+
+    for (const key of keys) {
+        const name = friendlyName(key.kind, address, counts[key.kind]++);
+        const localKeyId = hexBytes(key.fingerprint).slice(0, 20);
+        const keyBag = new pkijs.PKCS8ShroudedKeyBag({ parsedValue: pkijs.PrivateKeyInfo.fromBER(toArrayBuffer(key.pkcs8)) });
+        shrouded.push(keyBag);
+        bags.push(new pkijs.SafeBag({ bagId: PKCS8_SHROUDED_KEY_BAG, bagValue: keyBag, bagAttributes: bagAttributes(name, localKeyId) }));
+        const certBag = new pkijs.CertBag({ certId: X509_CERTIFICATE, parsedValue: pkijs.Certificate.fromBER(toArrayBuffer(key.certDer)) });
+        bags.push(new pkijs.SafeBag({ bagId: CERT_BAG, bagValue: certBag, bagAttributes: bagAttributes(name, localKeyId) }));
+    }
+
+    for (const keyBag of shrouded) {
+        await keyBag.makeInternalValues(
+            { password: utf8, contentEncryptionAlgorithm: AES_256_CBC, hmacHashAlgorithm: "SHA-256", iterationCount: KEY_EXPORT_ITERATIONS },
+            crypto,
+        );
+    }
+
+    const pfx = new pkijs.PFX({
+        parsedValue: {
+            integrityMode: 0,
+            authenticatedSafe: new pkijs.AuthenticatedSafe({ parsedValue: { safeContents: [{ privacyMode: 0, value: new pkijs.SafeContents({ safeBags: bags }) }] } }),
+        },
+    });
+    await pfx.parsedValue!.authenticatedSafe!.makeInternalValues({ safeContents: [{}] }, crypto);
+    await pfx.makeInternalValues(
+        { password: utf8, iterations: KEY_EXPORT_ITERATIONS, pbkdf2HashAlgorithm: { name: "SHA-256" }, hmacHashAlgorithm: "SHA-256" },
+        crypto,
+    );
+    return new Uint8Array(pfx.toSchema().toBER(false));
+}
+
+/**
+ * Builds the "Export keys for Outlook/phone" PKCS#12 for `input.mailboxUid` (see this module's comment) and records the
+ * export with restapi. Re-opens the vault with `masterPassword` - rejecting as `unlockWithPassword()` does on a wrong
+ * one - and never touches the in-memory session. Every opened private key and the master key are zeroed before this
+ * returns, whether or not it succeeds. Throws `NothingToExportError` when no key opens.
+ */
+export async function exportKeysAsPkcs12(input: KeyExportInput, client?: ApiClient): Promise<KeyExport> {
+    if (input.exportPassphrase.length < MIN_EXPORT_PASSPHRASE_LENGTH) {
+        throw new Error(`The export passphrase must be at least ${MIN_EXPORT_PASSPHRASE_LENGTH} characters.`);
+    }
+    const { vault, masterKey } = await openMasterKeyWithPassword(input.mailboxUid, input.masterPassword, client);
+    let opened: OpenedKey[] = [];
+    try {
+        opened = await openExportedKeys(input, vault, masterKey);
+        if (!opened.some((k) => k.kind !== "sign")) {
+            throw new NothingToExportError();
+        }
+        const pkcs12 = await buildPkcs12(opened, input.mailboxAddress, input.exportPassphrase);
+        const keys = opened.map(({ kind, fingerprint }) => ({ kind, fingerprint }));
+        await recordKeyExport(input.mailboxUid, keys, client);
+        return { pkcs12, keys };
+    } finally {
+        masterKey.fill(0);
+        for (const key of opened) {
+            key.pkcs8.fill(0);
+        }
+    }
+}