@rapidmx/web-client 0.35.0 → 0.37.0

package/dist/lib/crypto/keySession.js

@@ -21,8 +21,9 @@
  * follow-up, not a silent gap: a mailbox enrolled *only* with a passkey has no way to unlock through this
  * module today.
  */
-import { findActivePublicKey, getKeyVault } from "./keyvaultApi.js";
+import { findActivePublicKey, getKeyVault, isOpenPgpKey } from "./keyvaultApi.js";
 import { fromBase64 } from "./encoding.js";
+import { certificateHoldsKey } from "./keyPairMatch.js";
 import { importPrivateKeyPkcs8 } from "./keys.js";
 import { KeysLockedError, buildAad, openWithKey } from "./masterKey.js";
 import { deriveFromPassword, parseArgon2idKdfLabel } from "./passwordUnlock.js";
@@ -33,6 +34,8 @@ 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 const OPENPGP_PRIVATE_KEY_AAD_PURPOSE = "openpgp-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 +92,57 @@ 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)];
+}
+/**
+ * Makes an OpenPGP key this device has just enrolled (`openPgpKey.ts`'s `ensureOpenPgpKey()`) the active one of `unlocked`, so
+ * OpenPGP mail to it reads without another unlock - the same rules as `addZeroAccessKey()`.
+ */
+export function addOpenPgpKey(mailboxUid, unlocked, key) {
+    if (unlocked.destroyed || sessions.get(mailboxUid) !== unlocked) {
+        return;
+    }
+    unlocked.openPgpKeys = [key, ...(unlocked.openPgpKeys ?? []).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 +186,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 +205,19 @@ function destroyObject(unlocked) {
         unlocked.retainedEncryptionKeys.length = 0;
         delete unlocked.retainedEncryptionKeys;
     }
+    if (unlocked.zeroAccessKeys) {
+        unlocked.zeroAccessKeys.length = 0;
+        delete unlocked.zeroAccessKeys;
+    }
+    if (unlocked.openPgpKeys) {
+        // OpenPGP.js keeps a decrypted secret key's material in its own objects: wipe it there too.
+        for (const { privateKey } of unlocked.openPgpKeys) {
+            // Present at runtime on every `PrivateKey`, missing from OpenPGP.js's type declarations.
+            privateKey.clearPrivateParams();
+        }
+        unlocked.openPgpKeys.length = 0;
+        delete unlocked.openPgpKeys;
+    }
 }
 /** Finds the wrapped private key whose fingerprint matches a given published public key. */
 function findWrappedPrivateKey(vault, fingerprint) {
@@ -163,10 +238,15 @@ export class UnopenableEncryptionKeyError extends Error {
     }
 }
 /** Opens one wrapped PKCS#8 private key under `masterKey` and imports it (non-extractable by default, like
- * `importPrivateKeyPkcs8()` itself), zeroing the transient plaintext whether or not the import succeeds. */
-async function openPrivateKey(masterKey, wrapped, aad, algorithm, usages, extractable = false) {
+ * `importPrivateKeyPkcs8()` itself), zeroing the transient plaintext whether or not the import succeeds. With `certDer` - the server's
+ * certificate for it, unauthenticated - it rejects a key that certificate isn't the one of (`certificateHoldsKey()`), so a swapped
+ * certificate never pairs with the opened key. */
+async function openPrivateKey(masterKey, wrapped, aad, algorithm, usages, extractable = false, certDer) {
     const raw = await openWithKey(masterKey, wrapped, aad);
     try {
+        if (certDer && !(await certificateHoldsKey(certDer, raw))) {
+            throw new Error("The certificate isn't the key's.");
+        }
         return await importPrivateKeyPkcs8(raw, algorithm, usages, extractable);
     }
     finally {
@@ -177,7 +257,7 @@ async function openPrivateKey(masterKey, wrapped, aad, algorithm, usages, extrac
  * Opens the retained encryption keys onto `unlocked.retainedEncryptionKeys`: every published `encrypt` key in
  * `mailboxKeys` other than the active one (`activeFingerprint`), whatever its revocation or expiry, that has a wrapped
  * private key in the vault - de-duplicated by fingerprint, newest `notBefore` first, at most
- * `MAX_RETAINED_ENCRYPTION_KEYS`. A key that won't open or import, or whose certificate won't decode, is skipped and
+ * `MAX_RETAINED_ENCRYPTION_KEYS`. A key that won't open or import, or whose certificate won't decode or isn't the key's, is skipped and
  * added to `unopenableKeys`. Retained keys are imported non-extractable. Each key is attached as it opens, so a failed
  * unlock's `destroyObject()` drops those too.
  */
@@ -185,7 +265,7 @@ async function openRetainedEncryptionKeys(mailboxUid, mailboxKeys, vault, unlock
     const seen = new Set(activeFingerprint !== undefined ? [activeFingerprint] : []);
     const candidates = [];
     for (const publicKey of [...mailboxKeys].sort((a, b) => b.notBefore - a.notBefore)) {
-        const wrapped = publicKey.useType === "encrypt" && !seen.has(publicKey.fingerprint) ? findWrappedPrivateKey(vault, publicKey.fingerprint) : undefined;
+        const wrapped = publicKey.useType === "encrypt" && !isOpenPgpKey(publicKey) && !seen.has(publicKey.fingerprint) ? findWrappedPrivateKey(vault, publicKey.fingerprint) : undefined;
         if (!wrapped) {
             continue;
         }
@@ -199,7 +279,7 @@ async function openRetainedEncryptionKeys(mailboxUid, mailboxKeys, vault, unlock
     for (const { publicKey, wrapped } of candidates) {
         try {
             const certDer = fromBase64(publicKey.publicKey);
-            const privateKey = await openPrivateKey(unlocked.masterKey, wrapped, aad, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"], false);
+            const privateKey = await openPrivateKey(unlocked.masterKey, wrapped, aad, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"], false, certDer);
             (unlocked.retainedEncryptionKeys ?? (unlocked.retainedEncryptionKeys = [])).push({ fingerprint: publicKey.fingerprint, certDer, privateKey });
         }
         catch {
@@ -207,6 +287,78 @@ 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. So is one whose certificate (the
+ * server's, unauthenticated) isn't the private key's: this device seals to the active key's certificate - search index segments of
+ * end-to-end mail, protected meetings' keys - so a certificate swapped by the server must never become 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 certDer = fromBase64(publicKey.publicKey);
+            const raw = await openWithKey(unlocked.masterKey, wrapped, aad);
+            try {
+                if (!(await certificateHoldsKey(certDer, raw))) {
+                    throw new Error("The zero-access certificate isn't the key's.");
+                }
+                const privateKey = await importPrivateKeyPkcs8(raw, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"], false);
+                (unlocked.zeroAccessKeys ?? (unlocked.zeroAccessKeys = [])).push({ fingerprint: publicKey.fingerprint, certDer, privateKey });
+            }
+            finally {
+                raw.fill(0);
+            }
+        }
+        catch {
+            unopenableKeys.push(publicKey.fingerprint);
+        }
+        if (++opened === MAX_RETAINED_ENCRYPTION_KEYS + 1) {
+            break;
+        }
+    }
+}
+/**
+ * Opens the mailbox's OpenPGP secret keys into `unlocked.openPgpKeys`: its published OpenPGP certificates (`type: "openpgp"`) that
+ * have a wrapped secret key, the active one first (unrevoked, unexpired, latest `notBefore`), then the rest newest first, at most
+ * `MAX_RETAINED_ENCRYPTION_KEYS + 1`. OpenPGP.js is loaded only for a mailbox that has one. A key that won't open is listed in
+ * `unopenableKeys` and skipped.
+ */
+async function openOpenPgpKeys(mailboxUid, mailboxKeys, vault, unlocked, unopenableKeys) {
+    const now = Date.now();
+    const active = (key) => !key.revokedAt && key.notAfter > now;
+    const ordered = mailboxKeys
+        .filter((key) => isOpenPgpKey(key) && findWrappedPrivateKey(vault, key.fingerprint))
+        .sort((a, b) => Number(active(b)) - Number(active(a)) || b.notBefore - a.notBefore)
+        .slice(0, MAX_RETAINED_ENCRYPTION_KEYS + 1);
+    if (ordered.length === 0) {
+        return;
+    }
+    const { readSecretKey } = await import("./openpgp.js");
+    const aad = buildAad(mailboxUid, OPENPGP_PRIVATE_KEY_AAD_PURPOSE);
+    for (const publicKey of ordered) {
+        try {
+            const raw = await openWithKey(unlocked.masterKey, findWrappedPrivateKey(vault, publicKey.fingerprint), aad);
+            try {
+                (unlocked.openPgpKeys ?? (unlocked.openPgpKeys = [])).push({ fingerprint: publicKey.fingerprint, privateKey: await readSecretKey(raw) });
+            }
+            finally {
+                raw.fill(0);
+            }
+        }
+        catch {
+            unopenableKeys.push(publicKey.fingerprint);
+        }
+    }
+}
 /**
  * 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
@@ -219,13 +371,22 @@ async function openRetainedEncryptionKeys(mailboxUid, mailboxKeys, vault, unlock
  * "incorrect password," not a generic error, but this module doesn't presume a specific UI's error copy.
  * Once the master key has opened, the password is known to be right: an active signing key that then
  * won't open is skipped and listed in `UnlockResult.unopenableKeys` (so is a retained encryption key); an active
- * encryption key that won't
- * open still fails the unlock, with `UnopenableEncryptionKeyError`. Throws `KeysLockedError` when
+ * encryption key that won't open, or whose certificate isn't its own,
+ * still fails the unlock, with `UnopenableEncryptionKeyError`. Throws `KeysLockedError` when
  * `destroyUnlockedKeys()` locked this mailbox (or all mailboxes) while the unlock was in flight.
  */
 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 +398,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. */
@@ -326,17 +487,23 @@ async function openSession(mailboxUid, mailboxKeys, vault, masterKey, generation
         const encryptionPublicKey = findActivePublicKey(mailboxKeys, "encrypt");
         const wrappedEncryptionKey = encryptionPublicKey && findWrappedPrivateKey(vault, encryptionPublicKey.fingerprint);
         if (encryptionPublicKey && wrappedEncryptionKey) {
+            let encryptionCertDer;
             try {
+                // The certificate is the server's: one that isn't this key's - what this device encrypts its own copies to, and what it
+                // hands out as its S/MIME certificate - makes the key unopenable, exactly as a wrap that won't open.
+                encryptionCertDer = fromBase64(encryptionPublicKey.publicKey);
                 const aad = buildAad(mailboxUid, ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE);
-                unlocked.encryptionPrivateKey = await openPrivateKey(masterKey, wrappedEncryptionKey, aad, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"]);
+                unlocked.encryptionPrivateKey = await openPrivateKey(masterKey, wrappedEncryptionKey, aad, { name: "ECDH", namedCurve: "P-256" }, ["deriveBits"], false, encryptionCertDer);
             }
             catch (err) {
                 throw new UnopenableEncryptionKeyError(encryptionPublicKey.fingerprint, err);
             }
-            unlocked.encryptionCertDer = fromBase64(encryptionPublicKey.publicKey);
+            unlocked.encryptionCertDer = encryptionCertDer;
             unlocked.encryptionFingerprint = encryptionPublicKey.fingerprint;
         }
         await openRetainedEncryptionKeys(mailboxUid, mailboxKeys, vault, unlocked, encryptionPublicKey?.fingerprint, unopenableKeys);
+        await openZeroAccessKeys(mailboxUid, vault, unlocked, unopenableKeys);
+        await openOpenPgpKeys(mailboxUid, mailboxKeys, 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

@@ -10,9 +10,10 @@ import { ApiClient, ApiRequestError } from "../util/api.js";
 /** A cryptographic public key used to sign or encrypt messages — safe to expose publicly. Mirrors
  * `@rapidmx/restapi`'s `PublicKey` type exactly. */
 export interface PublicKey {
-    /** Base64-encoded DER X.509 certificate. */
+    /** Base64-encoded DER X.509 certificate - or, for `type: "openpgp"`, the binary OpenPGP transferable public key. */
     publicKey: string;
-    /** The key's type/format (e.g. `x509`). */
+    /** The key's type/format: `x509` (S/MIME), or `openpgp` - an OpenPGP certificate, which both encrypts and signs and is listed
+     * once, with `useType: "encrypt"` (restapi `specs/end-to-end_encryption.md` *OpenPGP Interoperability*). */
     type: string;
     useType: "sign" | "encrypt";
     /** SHA-256 fingerprint of the certificate, hex encoded. */
@@ -41,7 +42,29 @@ export interface WrappedPrivateKey {
     /** AEAD algorithm identifier (e.g. `AES-256-GCM`). */
     algorithm: string;
     fingerprint: string;
-    useType: "sign" | "encrypt";
+    useType: KeyUseType;
+    /** `"openpgp"` for an OpenPGP secret key (sealed with `OPENPGP_PRIVATE_KEY_AAD_PURPOSE`); absent for a PKCS#8 key. */
+    type?: string;
+}
+/** `PublicKey.type` of an OpenPGP certificate. */
+export declare const OPENPGP_KEY_TYPE = "openpgp";
+/** Whether `key` is an OpenPGP certificate (or an OpenPGP secret key's wrap). */
+export declare function isOpenPgpKey(key: {
+    type?: string;
+} | undefined): boolean;
+/** A key's format: `"openpgp"`, or `"x509"` for every other key (S/MIME). */
+export type KeyFormat = "x509" | "openpgp";
+export declare function keyFormat(key: {
+    type?: string;
+}): KeyFormat;
+/** 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. */
@@ -64,7 +87,12 @@ export interface MasterKeyWrap {
 export interface EncryptionPreference {
     lastSeen?: number;
     preferEncrypt: "mutual" | "nopreference";
+    /** Which end-to-end format the address would rather receive when a sender can use either (restapi
+     * `specs/end-to-end_encryption.md` *Choosing the format*). Absent: no preference. */
+    preferFormat?: EndToEndFormat;
 }
+/** The two end-to-end encryption formats. */
+export type EndToEndFormat = "smime" | "openpgp";
 /** A newly observed key that differs from a contact's pinned key of the same `useType` - restapi records it instead of
  * silently replacing the pin (the spec's Key Conflict Handling) until the user resolves it with `resolveKeyConflict()`.
  * A contact holds at most one per `useType`. Mirrors `@rapidmx/restapi`'s `KeyConflict`. */
@@ -102,6 +130,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 {
@@ -121,7 +152,7 @@ export declare function getKeyVault(mailboxUid: string, client?: ApiClient): Pro
  * `revocationReason` - a superseded key may still verify old mail (`isTrustedForVerification()`) but is never used for
  * new mail. Shared by `crypto/keySession.ts` (the
  * mailbox's own keys) and `crypto/composeSecurity.ts` (a recipient's discovered keys). */
-export declare function findActivePublicKey(keys: PublicKey[], useType: "sign" | "encrypt"): PublicKey | undefined;
+export declare function findActivePublicKey(keys: PublicKey[], useType: "sign" | "encrypt", format?: KeyFormat): PublicKey | undefined;
 /**
  * Whether `key` may still be trusted to *verify* existing signatures - never whether to sign or encrypt with it (that is
  * `findActivePublicKey()`, which skips every revoked key). Expired keys are trusted: mail signed while a key was valid
@@ -147,13 +178,17 @@ 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"`. */
     certificate?: string;
-    wrappedKey: Omit<WrappedPrivateKey, "fingerprint" | "useType">;
+    /** `"openpgp"` to enroll the mailbox's OpenPGP key (with `useType: "encrypt"`): self-certified, no CA. */
+    type?: string;
+    /** The OpenPGP public key (armored or base64 binary) - required, and only meaningful, with `type: "openpgp"`. */
+    publicKey?: string;
+    wrappedKey: Omit<WrappedPrivateKey, "fingerprint" | "useType" | "type">;
     /** Only meaningful the very first time a mailbox enrolls a key at all (bootstraps its master key). */
     masterKeyWraps?: MasterKeyWrap[];
 }
@@ -298,6 +333,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
@@ -320,6 +424,11 @@ export interface KeyLookupResult {
     keyConflicts?: KeyConflict[];
     /** Keys that were pinned before, newest first - see `PreviousKey`. */
     previousKeys?: PreviousKey[];
+    /** The format to use for a recipient reachable in both (restapi *Choosing the format*): the user's choice for the contact, else what
+     * the address advertises, else what it was last seen using. Absent when nothing says - S/MIME then. */
+    preferredFormat?: EndToEndFormat;
+    /** Where `preferredFormat` came from. */
+    preferredFormatSource?: "contact" | "advertised" | "observed";
 }
 /** Server-side Discovery: the server itself performs the `_rapidmx` DNS lookup and remote key-endpoint
  * fetch (browsers can't do DNS TXT lookups, and a direct cross-origin fetch would hit CORS), persisting
@@ -329,8 +438,11 @@ export declare function lookupKeys(mailboxUid: string, addr: string, client?: Ap
 /** What `trustSigner()` pins: the sender's address and the certificate that signed their message. */
 export interface TrustSignerInput {
     address: string;
-    /** Base64 DER of the signer certificate - `MessageSecurityResult.signerCertificate`. */
+    /** Base64 DER of the signer certificate - `MessageSecurityResult.signerCertificate` - or, with `type: "openpgp"`, an OpenPGP
+     * public key (armored or base64 binary): a signer's, a key attached to a message, or one the user pasted. */
     certificate: string;
+    /** `"openpgp"` to pin an OpenPGP key (it encrypts and signs); omitted for an X.509 signing certificate. */
+    type?: string;
 }
 /**
  * Thrown by `trustSigner()` when restapi answers `409`: a different signing key is already pinned for that address, so
@@ -363,6 +475,8 @@ export interface ResolveKeyConflictInput {
     /** For `"accept"`: base64 DER of the certificate to pin (e.g. `MessageSecurityResult.signerCertificate` of a
      * `signer_key_changed` result). Omitted, restapi pins the recorded conflict's `observedKey`. */
     certificate?: string;
+    /** `"openpgp"` for the contact's OpenPGP key (always `useType: "encrypt"`); omitted for its S/MIME certificate. */
+    type?: string;
 }
 /** The contact's resulting key state after `resolveKeyConflict()`. */
 export type ResolveKeyConflictResult = KeyLookupResult;
@@ -386,6 +500,13 @@ 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;
+    /** "Allow OpenPGP": whether mailboxes may enroll and publish OpenPGP keys, for mail with OpenPGP users. Absent from a server
+     * that predates it, which a caller treats as not allowed. */
+    allowOpenPgp?: 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

@@ -11,6 +11,15 @@
  * and `crypto/keys.ts` for the client-side cryptography that produces the values passed here.
  */
 import { ApiRequestError, withClient } from "../util/api.js";
+/** `PublicKey.type` of an OpenPGP certificate. */
+export const OPENPGP_KEY_TYPE = "openpgp";
+/** Whether `key` is an OpenPGP certificate (or an OpenPGP secret key's wrap). */
+export function isOpenPgpKey(key) {
+    return key?.type === OPENPGP_KEY_TYPE;
+}
+export function keyFormat(key) {
+    return isOpenPgpKey(key) ? "openpgp" : "x509";
+}
 /** `client`, given by every function below that calls the network, is an explicit `ApiClient` from `createApiClient()`
  * (e.g. one account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
  * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
@@ -24,10 +33,10 @@ export function getKeyVault(mailboxUid, client) {
  * `revocationReason` - a superseded key may still verify old mail (`isTrustedForVerification()`) but is never used for
  * new mail. Shared by `crypto/keySession.ts` (the
  * mailbox's own keys) and `crypto/composeSecurity.ts` (a recipient's discovered keys). */
-export function findActivePublicKey(keys, useType) {
+export function findActivePublicKey(keys, useType, format = "x509") {
     const now = Date.now();
     return keys
-        .filter((k) => k.useType === useType && !k.revokedAt && k.notAfter > now)
+        .filter((k) => k.useType === useType && keyFormat(k) === format && !k.revokedAt && k.notAfter > now)
         .sort((a, b) => b.notBefore - a.notBefore)[0];
 }
 /**
@@ -248,6 +257,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
@@ -288,7 +329,7 @@ export async function trustSigner(mailboxUid, input, client) {
     try {
         return await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/trust`, {
             method: "POST",
-            body: JSON.stringify({ address: input.address, certificate: input.certificate }),
+            body: JSON.stringify({ address: input.address, certificate: input.certificate, ...(input.type ? { type: input.type } : {}) }),
         });
     }
     catch (err) {
@@ -322,6 +363,7 @@ export async function resolveKeyConflict(mailboxUid, input, client) {
         action: input.action,
         expectedPinnedFingerprint: input.expectedPinnedFingerprint,
         ...(input.certificate !== undefined ? { certificate: input.certificate } : {}),
+        ...(input.type ? { type: input.type } : {}),
     };
     try {
         return await withClient(client, `/mail/mailboxes/${encodeURIComponent(mailboxUid)}/keys/resolve`, {

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

@@ -0,0 +1,25 @@
+import type { DecryptionKey } from "./smime.js";
+/** The `#` parameter of a link that carries a meeting key. */
+export declare const MEETING_KEY_FRAGMENT_PARAM = "k";
+/** A meeting key as its creator holds it. */
+export interface GeneratedMeetingKey {
+    /** PKCS#8 DER of the private key - what a link carries and a wrap seals. */
+    pkcs8: Uint8Array;
+    /** The self-signed certificate's DER - what the server stores and data is sealed to. */
+    certificateDer: Uint8Array;
+    /** SHA-256 of `certificateDer`, lowercase hex. */
+    fingerprint: string;
+}
+/** A new meeting key valid until `expiresAt` (its certificate's `notAfter`). */
+export declare function generateMeetingKey(expiresAt: Date): Promise<GeneratedMeetingKey>;
+/** The `#` part a guest's link carries for `pkcs8`: `k=<base64url>`. */
+export declare function meetingKeyFragment(pkcs8: Uint8Array): string;
+/** The meeting key in `hash` (a `location.hash`, with or without its `#`), or `undefined` when it carries none or it is malformed. */
+export declare function readMeetingKeyFragment(hash: string): Uint8Array | undefined;
+/** The meeting key `pkcs8` as the CMS code opens with it, and its live key for meeting `meetingUid`. Rejects a key that isn't P-256. */
+export declare function importMeetingKey(pkcs8: Uint8Array, certificateDer: Uint8Array, meetingUid: string): Promise<{
+    decryptionKey: DecryptionKey;
+    liveKey: CryptoKey;
+}>;
+/** The AES-256-GCM live key of meeting `meetingUid` from `ikm`, the meeting key's private scalar. Non-extractable. */
+export declare function deriveLiveKey(ikm: Uint8Array, meetingUid: string): Promise<CryptoKey>;