@rapidmx/web-client 0.35.0 → 0.36.0

package/dist/lib/crypto/keyExport.js

@@ -0,0 +1,161 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { fromBase64 } from "./encoding.js";
+import { findActivePublicKey, recordKeyExport } 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 = 100000;
+/** 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) };
+/** 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) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function hexBytes(hex) {
+    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, localKeyId) {
+    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, address, index) {
+    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, wrapped, aad) {
+    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, vault, masterKey) {
+    const opened = [];
+    const wrappedFor = (fingerprint) => vault.wrappedKeys.find((k) => k.fingerprint === fingerprint);
+    const take = async (kind, keys, purpose, max) => {
+        const aad = buildAad(input.mailboxUid, purpose);
+        const seen = new Set();
+        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, address, passphrase) {
+    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 = [];
+    const shrouded = [];
+    const counts = { "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, client) {
+    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 = [];
+    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);
+        }
+    }
+}

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

@@ -17,7 +17,8 @@
  * follow-up, not a silent gap: a mailbox enrolled *only* with a passkey has no way to unlock through this
  * module today.
  */
-import { type PublicKey } from "./keyvaultApi.js";
+import { type KeyVault, type PublicKey } from "./keyvaultApi.js";
+import type { ApiClient } from "../util/api.js";
 import { KeysLockedError } from "./masterKey.js";
 /** AAD purpose labels — MUST exactly match what `KeyEnrollmentGate.tsx` used when it originally
  * sealed each of these values, or `openWithKey()` fails (GCM authenticates the AAD, not just the
@@ -25,6 +26,7 @@ import { KeysLockedError } from "./masterKey.js";
 export declare const MASTER_KEY_AAD_PURPOSE = "master-key";
 export declare const SIGNING_PRIVATE_KEY_AAD_PURPOSE = "sign-private-key";
 export declare const ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE = "encrypt-private-key";
+export declare const ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE = "zero-access-private-key";
 export { KeysLockedError };
 /** How many retained (non-active) encryption keys an unlock opens at most: the most recently issued ones by
  * `notBefore`. Each costs an AEAD open and a key import at unlock, and `smime.ts`'s `decryptEnvelopedDataWithKeys()`
@@ -60,6 +62,17 @@ export interface UnlockedKeys {
      * that). A compromised key is kept because reading one's own mail encrypted to it is still needed. Absent when there
      * are none. */
     retainedEncryptionKeys?: RetainedEncryptionKey[];
+    /** The mailbox's zero-access private keys (restapi `specs/search.md` §3) - the keys the server encrypts mail at rest,
+     * index entries and sealed summaries to - the active one first, then retained ones newest first, at most
+     * `MAX_RETAINED_ENCRYPTION_KEYS + 1`. Decryption only. Absent when the mailbox has none (or none opened). */
+    zeroAccessKeys?: RetainedEncryptionKey[];
+    /** A shared mailbox opened through this user's member key wraps (`sharedMailboxKeys.ts`), not with its own master key: it holds
+     * only `zeroAccessKeys`, and `masterKey` is a per-key secret derived from its zero-access private key (what the local search
+     * index's key is derived from), never a key that opens the mailbox's vault. */
+    shared?: boolean;
+    /** A shared session only: the user's own mailboxes whose zero-access keys opened its member key wraps. Locking any of them locks it too -
+     * it was opened with their keys, so it doesn't outlive them. */
+    openedWith?: string[];
 }
 /** What changed in the session store — passed to every `subscribeKeySession()` listener. */
 export interface KeySessionEvent {
@@ -76,6 +89,28 @@ export type KeySessionListener = (event: KeySessionEvent) => void;
  * nothing. Returns an unsubscribe function.
  */
 export declare function subscribeKeySession(listener: KeySessionListener): () => void;
+/**
+ * Makes a zero-access key this device has just enrolled (`zeroAccessKey.ts`'s `provisionZeroAccessKey()`) the active one
+ * of `unlocked` - the session object the key's private half was sealed under - so zero-access mail encrypted to it reads
+ * without another unlock. Does nothing when `unlocked` is no longer this mailbox's session (it was locked or replaced
+ * meanwhile; the next unlock opens the key from the vault anyway).
+ */
+export declare function addZeroAccessKey(mailboxUid: string, unlocked: UnlockedKeys, key: RetainedEncryptionKey): void;
+/**
+ * Stores the keys of a shared mailbox opened through member key wraps (`sharedMailboxKeys.ts`'s `unlockSharedMailbox()`) as that mailbox's
+ * session, exactly as an unlock would - tracked for `destroyUnlockedKeys()`, and notified - unless the mailbox was locked since `generation`
+ * was taken (`sharedUnlockGeneration()`), when they are destroyed instead and `KeysLockedError` is thrown.
+ */
+export declare function installSharedSession(mailboxUid: string, unlocked: UnlockedKeys, generation: string): void;
+/** The lock generation to pass `installSharedSession()`, taken before a shared unlock starts its requests. */
+export declare function sharedUnlockGeneration(mailboxUid: string): string;
+/** Every mailbox unlocked this session with its own keys (not a shared one opened through member key wraps). */
+export declare function personallyUnlockedKeys(): UnlockedKeys[];
+/** `personallyUnlockedKeys()` with each mailbox's uid. */
+export declare function personalSessions(): {
+    mailboxUid: string;
+    unlocked: UnlockedKeys;
+}[];
 /** Reads back a mailbox's already-unlocked keys this session, or `undefined` if it hasn't been
  * unlocked yet (or was destroyed). Never triggers an unlock itself. */
 export declare function getUnlockedKeys(mailboxUid: string): UnlockedKeys | undefined;
@@ -133,6 +168,15 @@ export declare class UnopenableEncryptionKeyError extends Error {
  * `destroyUnlockedKeys()` locked this mailbox (or all mailboxes) while the unlock was in flight.
  */
 export declare function unlockWithPassword(mailboxUid: string, mailboxKeys: PublicKey[], password: string): Promise<UnlockResult>;
+/**
+ * Fetches `mailboxUid`'s vault and opens its master key with the password wrap, touching no session - for an operation that
+ * must re-prove the password even while the mailbox is unlocked (`keyExport.ts`). Rejects exactly as `unlockWithPassword()`
+ * does on a missing wrap, an unknown KDF or a wrong password. The caller owns the returned master key and must zero it.
+ */
+export declare function openMasterKeyWithPassword(mailboxUid: string, password: string, client?: ApiClient): Promise<{
+    vault: KeyVault;
+    masterKey: Uint8Array;
+}>;
 /** What `unlockWithRecoveryCode()` resolves with. */
 export interface RecoveryUnlockResult extends UnlockResult {
     /** The `methodId` of the recovery wrap the code opened (e.g. `"recovery-3"`). Recovery codes are single-use:

package/dist/lib/crypto/keySession.js

@@ -33,6 +33,7 @@ import { RECOVERY_KDF_LABEL, deriveFromRecoveryCode } from "./recoveryCode.js";
 export const MASTER_KEY_AAD_PURPOSE = "master-key";
 export const SIGNING_PRIVATE_KEY_AAD_PURPOSE = "sign-private-key";
 export const ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE = "encrypt-private-key";
+export const ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE = "zero-access-private-key";
 export { KeysLockedError };
 /** How many retained (non-active) encryption keys an unlock opens at most: the most recently issued ones by
  * `notBefore`. Each costs an AEAD open and a key import at unlock, and `smime.ts`'s `decryptEnvelopedDataWithKeys()`
@@ -89,6 +90,47 @@ export function subscribeKeySession(listener) {
         listeners.delete(listener);
     };
 }
+/**
+ * Makes a zero-access key this device has just enrolled (`zeroAccessKey.ts`'s `provisionZeroAccessKey()`) the active one
+ * of `unlocked` - the session object the key's private half was sealed under - so zero-access mail encrypted to it reads
+ * without another unlock. Does nothing when `unlocked` is no longer this mailbox's session (it was locked or replaced
+ * meanwhile; the next unlock opens the key from the vault anyway).
+ */
+export function addZeroAccessKey(mailboxUid, unlocked, key) {
+    if (unlocked.destroyed || sessions.get(mailboxUid) !== unlocked) {
+        return;
+    }
+    unlocked.zeroAccessKeys = [key, ...(unlocked.zeroAccessKeys ?? []).filter((k) => k.fingerprint !== key.fingerprint)];
+}
+/**
+ * Stores the keys of a shared mailbox opened through member key wraps (`sharedMailboxKeys.ts`'s `unlockSharedMailbox()`) as that mailbox's
+ * session, exactly as an unlock would - tracked for `destroyUnlockedKeys()`, and notified - unless the mailbox was locked since `generation`
+ * was taken (`sharedUnlockGeneration()`), when they are destroyed instead and `KeysLockedError` is thrown.
+ */
+export function installSharedSession(mailboxUid, unlocked, generation) {
+    if (lockGeneration(mailboxUid) !== generation) {
+        destroyObject(unlocked);
+        throw new KeysLockedError();
+    }
+    unlocked.shared = true;
+    sessions.set(mailboxUid, unlocked);
+    const objects = issued.get(mailboxUid) ?? new Set();
+    objects.add(weakHandle(unlocked));
+    issued.set(mailboxUid, objects);
+    notify({ mailboxUid, state: "unlocked" });
+}
+/** The lock generation to pass `installSharedSession()`, taken before a shared unlock starts its requests. */
+export function sharedUnlockGeneration(mailboxUid) {
+    return lockGeneration(mailboxUid);
+}
+/** Every mailbox unlocked this session with its own keys (not a shared one opened through member key wraps). */
+export function personallyUnlockedKeys() {
+    return personalSessions().map((session) => session.unlocked);
+}
+/** `personallyUnlockedKeys()` with each mailbox's uid. */
+export function personalSessions() {
+    return [...sessions].filter(([, unlocked]) => !unlocked.shared).map(([mailboxUid, unlocked]) => ({ mailboxUid, unlocked }));
+}
 /** Reads back a mailbox's already-unlocked keys this session, or `undefined` if it hasn't been
  * unlocked yet (or was destroyed). Never triggers an unlock itself. */
 export function getUnlockedKeys(mailboxUid) {
@@ -132,6 +174,14 @@ export function destroyUnlockedKeys(mailboxUid) {
         sessions.delete(uid);
         notify({ mailboxUid: uid, state: "locked" });
     }
+    // The shared mailboxes opened with this mailbox's keys go with it.
+    if (mailboxUid) {
+        for (const [uid, unlocked] of [...sessions]) {
+            if (unlocked.shared && unlocked.openedWith?.includes(mailboxUid)) {
+                destroyUnlockedKeys(uid);
+            }
+        }
+    }
 }
 function destroyObject(unlocked) {
     unlocked.masterKey.fill(0);
@@ -143,6 +193,10 @@ function destroyObject(unlocked) {
         unlocked.retainedEncryptionKeys.length = 0;
         delete unlocked.retainedEncryptionKeys;
     }
+    if (unlocked.zeroAccessKeys) {
+        unlocked.zeroAccessKeys.length = 0;
+        delete unlocked.zeroAccessKeys;
+    }
 }
 /** Finds the wrapped private key whose fingerprint matches a given published public key. */
 function findWrappedPrivateKey(vault, fingerprint) {
@@ -207,6 +261,33 @@ async function openRetainedEncryptionKeys(mailboxUid, mailboxKeys, vault, unlock
         }
     }
 }
+/**
+ * Opens the mailbox's zero-access private keys into `unlocked.zeroAccessKeys`: the vault's `zeroAccessKeys` that have a
+ * wrapped private key, the unrevoked one with the latest `notBefore` first, then the rest newest first, at most
+ * `MAX_RETAINED_ENCRYPTION_KEYS + 1`. A key that won't open is listed in `unopenableKeys` and skipped - zero-access mail
+ * encrypted to it doesn't decrypt on this device, but nothing else about the unlock depends on it.
+ */
+async function openZeroAccessKeys(mailboxUid, vault, unlocked, unopenableKeys) {
+    const ordered = [...(vault.zeroAccessKeys ?? [])].sort((a, b) => Number(!!a.revokedAt) - Number(!!b.revokedAt) || b.notBefore - a.notBefore);
+    const aad = buildAad(mailboxUid, ZERO_ACCESS_PRIVATE_KEY_AAD_PURPOSE);
+    let opened = 0;
+    for (const publicKey of ordered) {
+        const wrapped = findWrappedPrivateKey(vault, publicKey.fingerprint);
+        if (!wrapped || wrapped.useType !== "zero-access") {
+            continue;
+        }
+        try {
+            const privateKey = await openPrivateKey(unlocked.masterKey, wrapped, aad, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"], false);
+            (unlocked.zeroAccessKeys ?? (unlocked.zeroAccessKeys = [])).push({ fingerprint: publicKey.fingerprint, certDer: fromBase64(publicKey.publicKey), privateKey });
+        }
+        catch {
+            unopenableKeys.push(publicKey.fingerprint);
+        }
+        if (++opened === MAX_RETAINED_ENCRYPTION_KEYS + 1) {
+            break;
+        }
+    }
+}
 /**
  * Unlocks a mailbox's key vault with its password unlock method: fetches the vault, derives the
  * wrapping key from `password` using the *exact* KDF parameters that wrap was created with, unwraps
@@ -225,7 +306,16 @@ async function openRetainedEncryptionKeys(mailboxUid, mailboxKeys, vault, unlock
  */
 export async function unlockWithPassword(mailboxUid, mailboxKeys, password) {
     const generation = lockGeneration(mailboxUid);
-    const vault = await getKeyVault(mailboxUid);
+    const { vault, masterKey } = await openMasterKeyWithPassword(mailboxUid, password);
+    return openSession(mailboxUid, mailboxKeys, vault, masterKey, generation);
+}
+/**
+ * Fetches `mailboxUid`'s vault and opens its master key with the password wrap, touching no session - for an operation that
+ * must re-prove the password even while the mailbox is unlocked (`keyExport.ts`). Rejects exactly as `unlockWithPassword()`
+ * does on a missing wrap, an unknown KDF or a wrong password. The caller owns the returned master key and must zero it.
+ */
+export async function openMasterKeyWithPassword(mailboxUid, password, client) {
+    const vault = await getKeyVault(mailboxUid, client);
     const passwordWrap = vault.masterKeyWraps.find((w) => w.method === "password");
     if (!passwordWrap) {
         throw new Error("This mailbox has no password unlock method enrolled.");
@@ -237,7 +327,7 @@ export async function unlockWithPassword(mailboxUid, mailboxKeys, password) {
     const salt = fromBase64(passwordWrap.salt);
     const { wrappingKey } = await deriveFromPassword(password, salt, kdfParams);
     const masterKey = await openWithKey(wrappingKey, { ciphertext: passwordWrap.ciphertext, nonce: passwordWrap.nonce }, buildAad(mailboxUid, MASTER_KEY_AAD_PURPOSE));
-    return openSession(mailboxUid, mailboxKeys, vault, masterKey, generation);
+    return { vault, masterKey };
 }
 /** The one rejection for a recovery code that opens nothing - a wrong code and a vault with no recovery wraps
  * alike, so a UI can say "that recovery code didn't work" without learning (or revealing) which it was. */
@@ -337,6 +427,7 @@ async function openSession(mailboxUid, mailboxKeys, vault, masterKey, generation
             unlocked.encryptionFingerprint = encryptionPublicKey.fingerprint;
         }
         await openRetainedEncryptionKeys(mailboxUid, mailboxKeys, vault, unlocked, encryptionPublicKey?.fingerprint, unopenableKeys);
+        await openZeroAccessKeys(mailboxUid, vault, unlocked, unopenableKeys);
         if (lockGeneration(mailboxUid) !== generation) {
             // Locked (e.g. logout) while this unlock was awaiting - never restore keys after that.
             throw new KeysLockedError();

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

@@ -41,7 +41,16 @@ export interface WrappedPrivateKey {
     /** AEAD algorithm identifier (e.g. `AES-256-GCM`). */
     algorithm: string;
     fingerprint: string;
-    useType: "sign" | "encrypt";
+    useType: KeyUseType;
+}
+/** What a mailbox's own key is used for. `sign`/`encrypt` keys are published (`Mailbox.keys`); `zero-access` keys never are.
+ * Mirrors `@rapidmx/restapi`'s `KeyUseType`. */
+export type KeyUseType = "sign" | "encrypt" | "zero-access";
+/** A mailbox's zero-access key (restapi `specs/search.md` §3): the certificate the server encrypts mail at rest to on
+ * arrival. Same shape as `PublicKey`, but never published - only the vault's reader gets it (`KeyVault.zeroAccessKeys`).
+ * Mirrors `@rapidmx/restapi`'s `ZeroAccessKey`. */
+export interface ZeroAccessKey extends Omit<PublicKey, "useType" | "issuerCertificate"> {
+    useType: "zero-access";
 }
 /** One wrapped copy of the mailbox master key (MK), per unlock method. Mirrors `@rapidmx/restapi`'s
  * `MasterKeyWrap` exactly. */
@@ -102,6 +111,9 @@ export interface KeyVault {
      * (`enrollKey()`, `startSignEnrollment()`, `addMasterKeyWrap()`, `rekey()`), so restapi refuses it with `409` if
      * another device rotated the master key meanwhile. Absent from servers that don't track it yet. */
     masterKeyGeneration?: number;
+    /** The mailbox's zero-access certificates, newest last - returned with the vault because they are never published and
+     * an unlock needs them to decrypt zero-access mail. Absent from servers without zero-access encryption. */
+    zeroAccessKeys?: ZeroAccessKey[];
 }
 /** The optional optimistic check restapi applies to vault writes carrying key material sealed under the master key. */
 export interface ExpectedMasterKeyGeneration {
@@ -147,8 +159,8 @@ export declare function isTrustedForVerification(key: PublicKey): boolean;
  */
 export declare function signingKeyFingerprints(keys: PublicKey[] | undefined, previousKeys?: PreviousKey[]): string[];
 export interface EnrollKeyInput extends ExpectedMasterKeyGeneration {
-    useType: "sign" | "encrypt";
-    /** PEM-encoded PKCS#10 CSR — required (and only meaningful) for `useType: "encrypt"`; the server
+    useType: KeyUseType;
+    /** PEM-encoded PKCS#10 CSR — required (and only meaningful) for `useType: "encrypt"` and `"zero-access"`; the server
      * calls its own internal CA against this CSR. */
     csr?: string;
     /** An already-issued PEM certificate — required (and only meaningful) for `useType: "sign"`. */
@@ -298,6 +310,75 @@ export declare function addMasterKeyWrap(mailboxUid: string, wrap: MasterKeyWrap
  * than one wrap could share the same `method` (e.g. multiple passkeys). This alone does NOT revoke
  * access for anyone who already captured the wrapped blob — see `rekey()`. */
 export declare function removeMasterKeyWrap(mailboxUid: string, method: string, methodId?: string, client?: ApiClient): Promise<KeyVault>;
+/** One member's copy of a shared mailbox's zero-access private key: base64 CMS of its PKCS#8, to the member's own zero-access certificate. */
+export interface MemberKeyWrap {
+    memberUserUid: string;
+    recipientFingerprint: string;
+    zeroAccessKeyFingerprint: string;
+    cms: string;
+    createdAt?: number;
+}
+/** One member in `SharedKeyStatus`. */
+export interface SharedKeyMember {
+    userUid: string;
+    full: boolean;
+    /** Their own zero-access certificate - absent until they first sign in and get one. */
+    certificate?: ZeroAccessKey;
+    /** The mailbox's zero-access keys they hold a wrap of. */
+    wrapped: string[];
+}
+/** Where a shared mailbox's zero-access key stands with its members - restapi `GET /mail/mailboxes/:id/keyvault/members`. */
+export interface SharedKeyStatus {
+    ownerless: boolean;
+    /** The caller: the mailbox's owner, one of its members, or neither (an administrator acting through a role). */
+    role?: "owner" | "member" | "other";
+    activeKeyFingerprint?: string;
+    zeroAccessKeys: ZeroAccessKey[];
+    members: SharedKeyMember[];
+    /** Members with a certificate but no wrap of the active key. */
+    pending: string[];
+    /** Users holding wraps who are no longer members. */
+    departed: string[];
+    /** A departed user holds the active key: a new key must be provisioned. */
+    rotationPending: boolean;
+    /** The caller may change the wraps. */
+    manager: boolean;
+    /** A mailbox without an owner assigned to an escrow scope: that scope. */
+    escrowScopeId?: string;
+    /** Its zero-access keys (fingerprints) with no escrow copy for `escrowScopeId` yet. Absent from servers that predate it. */
+    escrowPending?: string[];
+}
+/** An escrow copy of a mailbox-without-an-owner's zero-access private key, as `putZeroAccessEscrowWraps()` sends it: CMS of its PKCS#8 to
+ * the escrow scope's certificate (`getEscrowInfo()`). */
+export interface ZeroAccessEscrowWrapInput {
+    escrowScopeId: string;
+    zeroAccessKeyFingerprint: string;
+    /** Base64 DER CMS `EnvelopedData`. */
+    cms: string;
+}
+export declare function getSharedKeyStatus(mailboxUid: string, client?: ApiClient): Promise<SharedKeyStatus>;
+/** The caller's own member key wraps of `mailboxUid` (`[]` for its owner and for a member still waiting). */
+export declare function getMyMemberKeyWraps(mailboxUid: string, client?: ApiClient): Promise<MemberKeyWrap[]>;
+export declare function putMemberKeyWraps(mailboxUid: string, wraps: MemberKeyWrap[], client?: ApiClient): Promise<SharedKeyStatus>;
+/** Removes every wrap of a user who is no longer a member - the last step of a rotation. */
+export declare function removeMemberKeyWraps(mailboxUid: string, memberUserUid: string, client?: ApiClient): Promise<SharedKeyStatus>;
+/** Provisions (or rotates) a mailbox-without-an-owner's zero-access key with its member wraps, in one write - and, for a mailbox assigned to
+ * an escrow scope, its escrow copy (required then). */
+export declare function enrollSharedZeroAccessKey(mailboxUid: string, input: {
+    csr: string;
+    wraps: Omit<MemberKeyWrap, "zeroAccessKeyFingerprint">[];
+    escrowWrap?: Omit<ZeroAccessEscrowWrapInput, "zeroAccessKeyFingerprint">;
+}, client?: ApiClient): Promise<SharedKeyStatus>;
+/** Adds the escrow copies of a mailbox-without-an-owner's zero-access keys its escrow scope is missing (`SharedKeyStatus.escrowPending`). */
+export declare function putZeroAccessEscrowWraps(mailboxUid: string, wraps: ZeroAccessEscrowWrapInput[], client?: ApiClient): Promise<SharedKeyStatus>;
+/** One key a "Export keys for Outlook/phone" file held, as `recordKeyExport()` reports it. */
+export interface ExportedKeyRecord {
+    kind: "zero-access" | "encrypt" | "sign";
+    fingerprint: string;
+}
+/** Records with restapi that the owner exported these private keys (`key_vault.export` in the audit log). `keyExport.ts`
+ * calls it before handing over the file, so an export the server refuses to record isn't handed over. Owner-only. */
+export declare function recordKeyExport(mailboxUid: string, keys: ExportedKeyRecord[], client?: ApiClient): Promise<void>;
 export interface RekeyInput extends ExpectedMasterKeyGeneration {
     wrappedKeys: WrappedPrivateKey[];
     /** Every wrap of the new master key. For a mailbox assigned an escrow scope, this must include a fresh escrow wrap
@@ -386,6 +467,10 @@ export interface EncryptionPolicy {
     encryptSameOrg: PolicyState;
     encryptFederated: PolicyState;
     encryptExternal: PolicyState;
+    /** "Allow zero-access encryption": whether mailboxes may store mail encrypted at rest. Always present from a server that
+     * supports zero-access encryption (its stored value or the server default); absent from one that doesn't, which a
+     * caller treats as not allowed. */
+    allowZeroAccess?: boolean;
 }
 /** The system-wide encryption policy (readable by any authenticated user, used to decide what encryption
  * controls a compose UI should offer). */

package/dist/lib/crypto/keyvaultApi.js

@@ -248,6 +248,38 @@ export function removeMasterKeyWrap(mailboxUid, method, methodId, client) {
         method: "DELETE",
     });
 }
+const vaultPath = (mailboxUid) => `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault`;
+export function getSharedKeyStatus(mailboxUid, client) {
+    return withClient(client, `${vaultPath(mailboxUid)}/members`);
+}
+/** The caller's own member key wraps of `mailboxUid` (`[]` for its owner and for a member still waiting). */
+export function getMyMemberKeyWraps(mailboxUid, client) {
+    return withClient(client, `${vaultPath(mailboxUid)}/member-wraps`);
+}
+export function putMemberKeyWraps(mailboxUid, wraps, client) {
+    return withClient(client, `${vaultPath(mailboxUid)}/member-wraps`, { method: "PUT", body: JSON.stringify({ wraps }) });
+}
+/** Removes every wrap of a user who is no longer a member - the last step of a rotation. */
+export function removeMemberKeyWraps(mailboxUid, memberUserUid, client) {
+    return withClient(client, `${vaultPath(mailboxUid)}/member-wraps/${encodeURIComponent(memberUserUid)}`, { method: "DELETE" });
+}
+/** Provisions (or rotates) a mailbox-without-an-owner's zero-access key with its member wraps, in one write - and, for a mailbox assigned to
+ * an escrow scope, its escrow copy (required then). */
+export function enrollSharedZeroAccessKey(mailboxUid, input, client) {
+    return withClient(client, `${vaultPath(mailboxUid)}/shared-zero-access-key`, { method: "POST", body: JSON.stringify(input) });
+}
+/** Adds the escrow copies of a mailbox-without-an-owner's zero-access keys its escrow scope is missing (`SharedKeyStatus.escrowPending`). */
+export function putZeroAccessEscrowWraps(mailboxUid, wraps, client) {
+    return withClient(client, `${vaultPath(mailboxUid)}/escrow-wraps`, { method: "PUT", body: JSON.stringify({ wraps }) });
+}
+/** Records with restapi that the owner exported these private keys (`key_vault.export` in the audit log). `keyExport.ts`
+ * calls it before handing over the file, so an export the server refuses to record isn't handed over. Owner-only. */
+export async function recordKeyExport(mailboxUid, keys, client) {
+    await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keyvault/exports`, {
+        method: "POST",
+        body: JSON.stringify({ keys }),
+    });
+}
 /** Full, atomic replacement of the mailbox's key-vault contents — the only real revocation mechanism
  * for a captured wrap. Restricted server-side to the mailbox's actual owner. Refused (409) while a signing enrollment
  * holding a wrapped key is in flight (see `cancelSignEnrollment()`), or when an escrowed mailbox's request carries no

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;