@rapidmx/web-client 0.35.0 → 0.37.0

package/dist/lib/videoconf/protectedMeetings.js

@@ -0,0 +1,181 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The organizer's side of a protected video meeting (meet-plugin `specs/meeting_privacy.md`): a meeting whose organizer has a zero-access
+ * key gets a temporary meeting key, made here. Its title and invitees' names are sealed to the meeting key and the organizer's
+ * zero-access certificate; the meeting key itself is wrapped to the organizer's zero-access certificate, so any of the organizer's
+ * devices can reopen it; and every participant's link carries the key after `#k=`, which this module supplies on each save that sends an
+ * invitation (`invitationContent.meetingLinkSecrets`) and on the organizer's own join link - never stored by the server.
+ *
+ * The meeting key is discarded an hour after the event ends (the last occurrence's end for a series with an end; five years at most).
+ */
+import { fromBase64, toBase64 } from "../crypto/encoding.js";
+import { getUnlockedKeys, subscribeKeySession } from "../crypto/keySession.js";
+import { generateMeetingKey, meetingKeyFragment } from "../crypto/meetingKeys.js";
+import { decryptEnvelopedDataWithKeys, encryptForRecipients } from "../crypto/smime.js";
+import { getVideoMeeting, updateVideoMeeting } from "./videoMeetingsApi.js";
+/** How long after the meeting ends its key is kept (`mail:videoconf:key_grace_minutes`' default). */
+export const MEETING_KEY_GRACE_MS = 60 * 60000;
+/** The longest a meeting key is kept: a series without an end keeps it this long, just inside the server's limit. */
+const MAX_KEY_LIFETIME_MS = 5 * 365 * 24 * 60 * 60000;
+/** Link keys by meeting uid, each with the organizer mailbox it belongs to: a protected meeting's key is opened once, and forgotten when
+ * that mailbox's keys are locked. `fragment: null`: a meeting known to be unprotected. */
+const fragments = new Map();
+/** Forgets every opened meeting key (sign-out, or the test seam). */
+export function clearMeetingKeys() {
+    fragments.clear();
+}
+let watchingKeys = false;
+/** Records `uid`'s link key, forgetting it - like everything opened with a mailbox's keys - once that mailbox locks. Subscribed on the
+ * first key remembered, not on import. */
+function remember(uid, mailboxUid, fragment) {
+    if (!watchingKeys) {
+        watchingKeys = true;
+        subscribeKeySession(({ mailboxUid: locked, state }) => {
+            if (state === "locked") {
+                for (const [meetingUid, entry] of fragments) {
+                    if (entry.mailboxUid === locked) {
+                        fragments.delete(meetingUid);
+                    }
+                }
+            }
+        });
+    }
+    // A key opened or minted across an await the mailbox locked during: the lock's clear has already run, so it isn't kept.
+    if (fragment !== null && !getUnlockedKeys(mailboxUid)) {
+        return;
+    }
+    fragments.set(uid, { mailboxUid, fragment });
+}
+/** Meeting `uid`'s remembered link key - `null` for one known to be unprotected - or `undefined` when none is remembered, or its mailbox
+ * isn't unlocked here (a key is never handed out past its mailbox's lock). */
+function rememberedFragment(uid) {
+    const entry = fragments.get(uid);
+    if (!entry || (entry.fragment !== null && !getUnlockedKeys(entry.mailboxUid))) {
+        return undefined;
+    }
+    return entry.fragment;
+}
+/** When a meeting ending at `endDate` - the last occurrence's end, for a series that has one - has its key discarded. */
+export function meetingKeyExpiry(endDate, now = Date.now()) {
+    return new Date(Math.min(endDate.valueOf() + MEETING_KEY_GRACE_MS, now + MAX_KEY_LIFETIME_MS));
+}
+/** The organizer mailbox's active zero-access key, while the mailbox is unlocked. */
+function organizerKey(mailboxUid) {
+    return getUnlockedKeys(mailboxUid)?.zeroAccessKeys?.[0];
+}
+/** What protects a new meeting of `mailboxUid` titled `title` with `invitees`, its key discarded at `expiresAt` - or `undefined` when
+ * the mailbox has no zero-access key unlocked here (the meeting is then not protected). `fragment` is every participant's link key. */
+export async function protectMeeting(mailboxUid, title, invitees, expiresAt) {
+    const organizer = organizerKey(mailboxUid);
+    if (!organizer) {
+        return undefined;
+    }
+    const key = await generateMeetingKey(expiresAt);
+    const seal = async (value) => toBase64(await encryptForRecipients(new TextEncoder().encode(JSON.stringify(value)), [key.certificateDer, organizer.certDer]));
+    return {
+        protection: {
+            meetingKey: { certificate: toBase64(key.certificateDer) },
+            keyExpiresAt: expiresAt.toISOString(),
+            keyWraps: [{ mailboxUid, recipientFingerprint: organizer.fingerprint, kind: "meeting-key", cms: toBase64(await encryptForRecipients(key.pkcs8, [organizer.certDer])) }],
+            sealedFields: { title: await seal(title) },
+        },
+        invitees: await Promise.all(invitees.map(async (invitee) => (invitee.displayName ? { email: invitee.email, sealedFields: { displayName: await seal(invitee.displayName) } } : { email: invitee.email }))),
+        fragment: meetingKeyFragment(key.pkcs8),
+    };
+}
+/** Remembers a just-created meeting's link key - `null` for one that isn't protected - so the save that invites to it needn't fetch the
+ * meeting or reopen its wrap. `mailboxUid` is the organizer's mailbox: its lock forgets the key. */
+export function rememberMeetingKey(meetingUid, fragment, mailboxUid) {
+    remember(meetingUid, mailboxUid, fragment);
+}
+/** `meeting`'s link key - remembered, or opened from the organizer's wrap with the mailbox's unlocked zero-access keys - or `undefined`
+ * when it isn't protected or can't be opened here. Never rejects. */
+export async function meetingKeyFragmentOf(meeting) {
+    if (!meeting.keyProtected) {
+        return undefined;
+    }
+    const known = rememberedFragment(meeting.uid);
+    if (known !== undefined) {
+        return known ?? undefined;
+    }
+    const keys = getUnlockedKeys(meeting.mailboxUid)?.zeroAccessKeys;
+    const wrap = meeting.keyWraps?.find((candidate) => keys?.some((key) => key.fingerprint === candidate.recipientFingerprint));
+    if (!keys?.length || !wrap) {
+        return undefined;
+    }
+    try {
+        const fragment = meetingKeyFragment(await decryptEnvelopedDataWithKeys(fromBase64(wrap.cms), keys));
+        // Locked while it was opened: neither kept nor handed out.
+        if (!getUnlockedKeys(meeting.mailboxUid)) {
+            return undefined;
+        }
+        remember(meeting.uid, meeting.mailboxUid, fragment);
+        return fragment;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `meeting`'s organizer join link, with the meeting key after `#` when it is protected - `null` when there is none, or the key can't
+ * be opened here (a protected meeting can't be joined without it). */
+export async function organizerJoinLink(meeting) {
+    if (!meeting.organizerJoinUrl) {
+        return null;
+    }
+    if (!meeting.keyProtected) {
+        return meeting.organizerJoinUrl;
+    }
+    const fragment = await meetingKeyFragmentOf(meeting);
+    return fragment ? `${meeting.organizerJoinUrl}#${fragment}` : null;
+}
+/** For a save of `event` that may invite: every attendee's link key (`invitationContent.meetingLinkSecrets`), when its video meeting is
+ * protected and its key opens here - else `undefined`. Never rejects. */
+export async function meetingLinkSecrets(event, client) {
+    if (!event.videoMeetingUid) {
+        return undefined;
+    }
+    try {
+        const known = rememberedFragment(event.videoMeetingUid);
+        const fragment = known !== undefined ? known : await meetingKeyFragmentOf(await getVideoMeeting(event.videoMeetingUid, client));
+        if (!fragment) {
+            return undefined;
+        }
+        const organizer = event.organizer?.address.trim().toLowerCase();
+        const secrets = {};
+        for (const attendee of event.attendees ?? []) {
+            const address = attendee.address.trim().toLowerCase();
+            if (address && address !== organizer) {
+                secrets[address] = fragment;
+            }
+        }
+        return Object.keys(secrets).length > 0 ? secrets : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Moves the key expiry of meeting `meetingUid` - when it is protected - to follow its event's new end, `endDate` (the last occurrence's
+ * end, for a series): its key is discarded an hour after the end it was made for, so a meeting moved later (or a series extended) would
+ * otherwise be unjoinable by then. Best effort, after the event itself is saved: a failure is logged, never thrown.
+ */
+export async function followMeetingKeyExpiry(meetingUid, endDate, client) {
+    try {
+        if (fragments.get(meetingUid)?.fragment === null) {
+            return;
+        }
+        const meeting = await getVideoMeeting(meetingUid, client);
+        const keyExpiresAt = meetingKeyExpiry(endDate);
+        // Unprotected, or already right to the minute (an unchanged end).
+        if (!meeting.keyProtected || (meeting.keyExpiresAt && Math.abs(new Date(meeting.keyExpiresAt).valueOf() - keyExpiresAt.valueOf()) < 60000)) {
+            return;
+        }
+        await updateVideoMeeting(meetingUid, { keyExpiresAt: keyExpiresAt.toISOString() }, client);
+    }
+    catch (err) {
+        console.warn("Could not move the video meeting's key expiry to the event's new end", err);
+    }
+}

package/dist/lib/videoconf/videoMeetingsApi.d.ts

@@ -16,6 +16,7 @@
  * Response bodies are typed, not runtime-validated, matching this library's convention for a plain typed
  * `apiFetch<T>()` call (see `crypto/signingProviderApi.ts`'s own note on the same choice).
  */
+import type { MeetingProtectionInput } from "./protectedMeetings.js";
 import { ApiClient } from "../util/api.js";
 import { ListParams } from "../util/apiQuery.js";
 export type { ListParams };
@@ -38,6 +39,16 @@ export interface VideoMeeting {
      * (its oldest non-cancelled public meeting - see that app's own doc comment) out of `listVideoMeetings()`'s
      * results. */
     dateCreated: string;
+    /** Protected end to end (meet-plugin `specs/meeting_privacy.md`): `title` is `"Meeting"`, the real one sealed, and every link works
+     * only with the meeting key after `#` - see `protectedMeetings.ts`. */
+    keyProtected?: boolean | null;
+    /** A protected meeting's key, sealed to the organizer's zero-access certificate. */
+    keyWraps?: {
+        mailboxUid: string;
+        recipientFingerprint: string;
+        kind: string;
+        cms: string;
+    }[] | null;
 }
 /**
  * A meeting as fetched by `getVideoMeeting()` or listed by `listVideoMeetings()` — the entity plus whichever join
@@ -67,8 +78,9 @@ export interface VideoMeetingInviteeJoinInfo extends VideoMeetingInvitee {
 export interface CreateVideoMeetingInput {
     /** The mailbox that owns the meeting — the one whose ACL every later call on it is checked against. */
     mailboxUid: string;
-    /** Non-empty, at most 200 characters (the server rejects anything else with a 400). */
-    title: string;
+    /** Non-empty, at most 200 characters (the server rejects anything else with a 400). Omitted for a protected meeting, whose title is
+     * sealed in `protection`. */
+    title?: string;
     visibility: VideoMeetingVisibility;
     /** The `CalendarEvent` this meeting is being minted for, when there is one. */
     calendarEventUid?: string;
@@ -77,7 +89,14 @@ export interface CreateVideoMeetingInput {
     /** Required, and non-empty, for a `"private"` meeting — the server mints one personal join link per entry
      * and 400s a private meeting with none. Never send the organizer here: they reach their own meeting
      * through ownership (and `organizerJoinUrl`), not as a guest. */
-    invitees?: VideoMeetingInvitee[];
+    invitees?: (VideoMeetingInvitee | {
+        email: string;
+        sealedFields?: {
+            displayName: string;
+        };
+    })[];
+    /** Makes the meeting protected end to end - `protectMeeting()` in `protectedMeetings.ts`. */
+    protection?: MeetingProtectionInput;
 }
 export interface VideoMeetingCreateResult {
     meeting: VideoMeeting;
@@ -101,8 +120,10 @@ export declare function createVideoMeeting(input: CreateVideoMeetingInput, clien
 export interface UpdateVideoMeetingInput {
     title?: string;
     status?: "cancelled";
+    /** A protected meeting's new key expiry (ISO), when its event's end moved - `followMeetingKeyExpiry()` in `protectedMeetings.ts`. */
+    keyExpiresAt?: string;
 }
-/** Renames or cancels a meeting. Requires UPDATE on its owning mailbox. */
+/** Renames, cancels or moves the key expiry of a meeting. Requires UPDATE on its owning mailbox. */
 export declare function updateVideoMeeting(uid: string, input: UpdateVideoMeetingInput, client?: ApiClient): Promise<VideoMeeting>;
 /** Fetches one meeting, with the organizer's own join link when it has one. Requires READ on its owning mailbox. */
 export declare function getVideoMeeting(uid: string, client?: ApiClient): Promise<VideoMeetingDetail>;

package/dist/lib/videoconf/videoMeetingsApi.js

@@ -29,7 +29,7 @@ import { buildQuery } from "../util/apiQuery.js";
 export function createVideoMeeting(input, client) {
     return withClient(client, "/mail/video-meetings", { method: "POST", body: JSON.stringify(input) });
 }
-/** Renames or cancels a meeting. Requires UPDATE on its owning mailbox. */
+/** Renames, cancels or moves the key expiry of a meeting. Requires UPDATE on its owning mailbox. */
 export function updateVideoMeeting(uid, input, client) {
     return withClient(client, `/mail/video-meetings/${encodeURIComponent(uid)}`, { method: "PUT", body: JSON.stringify(input) });
 }

package/dist/lib/zeroAccess/sealedMoves.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A calendar event, contact or task whose content is sealed to its mailbox's zero-access key - field by field (`sealedFields`), as one
+ * blob (`sealedContent`, an event from a zero-access invitation) or its photo (`photoSealed`) - can't move to another mailbox: what it
+ * keeps sealed is addressed to the mailbox it is in, and the server can't seal it again to the destination's key. restapi refuses such a
+ * move with a `409` (`ZeroAccessRouteSealing.refuseSealedMove()`).
+ *
+ * The record API wrappers (`updateContact()`, `updateCalendarEvent()`, `updateTask()`) refuse it before sending anything when they know the
+ * record (`guardSealedMove()`), and turn the server's refusal into the same `SealedMoveError` when they don't - one request, so nothing is
+ * left half moved. A UI offering a move asks `canMoveToMailbox()` first, and shows `SealedMoveError`'s message.
+ */
+import { ApiRequestError } from "../util/api.js";
+/** The fields of a record that say whether its content is sealed, and where. */
+export interface MovableRecord {
+    mailboxUid: string;
+    sealedFields?: Record<string, string> | null;
+    sealedContent?: unknown;
+    photoSealed?: boolean | null;
+}
+/** What a refused move says. */
+export declare const SEALED_MOVE_MESSAGE = "This item is protected by its mailbox's zero-access encryption, so it can't be moved to another mailbox. Create a copy there instead.";
+/** `SealedMoveError.code`. */
+export declare const SEALED_MOVE_CODE = "sealed-move";
+/** restapi's `ApiErrors.INVALID_REQUEST`, the code of its sealed-move refusal and of its other zero-access refusals (a version conflict,
+ * also a `409`, is `api-012`; an identifier already taken, `api-011`). */
+export declare const INVALID_REQUEST_CODE = "api-003";
+/** A move of a protected record to another mailbox, refused - by this client before sending it, or by the server. Nothing was written. */
+export declare class SealedMoveError extends ApiRequestError {
+    constructor(message?: string);
+}
+/** Whether `record` keeps any of its content sealed to its mailbox's key. */
+export declare function isSealedRecord(record: MovableRecord): boolean;
+/** Whether `record` may move to mailbox `targetMailboxUid`: always within its own mailbox, and to another only when nothing of it is sealed. */
+export declare function canMoveToMailbox(record: MovableRecord, targetMailboxUid: string): boolean;
+/** Whether `err` is restapi's refusal of a sealed record's move. */
+export declare function isSealedMoveRefusal(err: unknown): err is ApiRequestError;
+/**
+ * Runs `write`, a save of a record that sets its `mailboxUid` to `targetMailboxUid` (`undefined`: the save doesn't set it). With `current`,
+ * the record as this device has it, a move of a sealed one is refused before anything is sent. A move the server refuses for the same reason
+ * rejects with `SealedMoveError` too.
+ */
+export declare function guardSealedMove<T>(current: MovableRecord | undefined, targetMailboxUid: string | undefined, write: () => Promise<T>): Promise<T>;

package/dist/lib/zeroAccess/sealedMoves.js

@@ -0,0 +1,63 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * A calendar event, contact or task whose content is sealed to its mailbox's zero-access key - field by field (`sealedFields`), as one
+ * blob (`sealedContent`, an event from a zero-access invitation) or its photo (`photoSealed`) - can't move to another mailbox: what it
+ * keeps sealed is addressed to the mailbox it is in, and the server can't seal it again to the destination's key. restapi refuses such a
+ * move with a `409` (`ZeroAccessRouteSealing.refuseSealedMove()`).
+ *
+ * The record API wrappers (`updateContact()`, `updateCalendarEvent()`, `updateTask()`) refuse it before sending anything when they know the
+ * record (`guardSealedMove()`), and turn the server's refusal into the same `SealedMoveError` when they don't - one request, so nothing is
+ * left half moved. A UI offering a move asks `canMoveToMailbox()` first, and shows `SealedMoveError`'s message.
+ */
+import { ApiRequestError } from "../util/api.js";
+/** What a refused move says. */
+export const SEALED_MOVE_MESSAGE = "This item is protected by its mailbox's zero-access encryption, so it can't be moved to another mailbox. Create a copy there instead.";
+/** `SealedMoveError.code`. */
+export const SEALED_MOVE_CODE = "sealed-move";
+/** restapi's `ApiErrors.INVALID_REQUEST`, the code of its sealed-move refusal and of its other zero-access refusals (a version conflict,
+ * also a `409`, is `api-012`; an identifier already taken, `api-011`). */
+export const INVALID_REQUEST_CODE = "api-003";
+/** A move of a protected record to another mailbox, refused - by this client before sending it, or by the server. Nothing was written. */
+export class SealedMoveError extends ApiRequestError {
+    constructor(message = SEALED_MOVE_MESSAGE) {
+        super(message, 409, SEALED_MOVE_CODE);
+        this.name = "SealedMoveError";
+    }
+}
+/** Whether `record` keeps any of its content sealed to its mailbox's key. */
+export function isSealedRecord(record) {
+    return (!!record.sealedFields && Object.keys(record.sealedFields).length > 0) || !!record.sealedContent || !!record.photoSealed;
+}
+/** Whether `record` may move to mailbox `targetMailboxUid`: always within its own mailbox, and to another only when nothing of it is sealed. */
+export function canMoveToMailbox(record, targetMailboxUid) {
+    return targetMailboxUid === record.mailboxUid || !isSealedRecord(record);
+}
+/** Whether `err` is restapi's refusal of a sealed record's move. */
+export function isSealedMoveRefusal(err) {
+    return err instanceof SealedMoveError || (err instanceof ApiRequestError && err.status === 409 && err.code === INVALID_REQUEST_CODE);
+}
+/**
+ * Runs `write`, a save of a record that sets its `mailboxUid` to `targetMailboxUid` (`undefined`: the save doesn't set it). With `current`,
+ * the record as this device has it, a move of a sealed one is refused before anything is sent. A move the server refuses for the same reason
+ * rejects with `SealedMoveError` too.
+ */
+export async function guardSealedMove(current, targetMailboxUid, write) {
+    if (targetMailboxUid === undefined) {
+        return write();
+    }
+    if (current && !canMoveToMailbox(current, targetMailboxUid)) {
+        throw new SealedMoveError();
+    }
+    try {
+        return await write();
+    }
+    catch (err) {
+        if (current?.mailboxUid !== targetMailboxUid && isSealedMoveRefusal(err) && !(err instanceof SealedMoveError)) {
+            throw new SealedMoveError();
+        }
+        throw err;
+    }
+}

package/dist/lib/zeroAccess/sealedRecords.d.ts

@@ -0,0 +1,29 @@
+/** A record that may carry sealed fields. */
+export interface SealedRecord {
+    mailboxUid: string;
+    /** Protected field name -> base64 CMS of its JSON value. */
+    sealedFields?: Record<string, string> | null;
+}
+/** Forgets every opened value (a mailbox locking, or the test seam). */
+export declare function clearSealedRecords(): void;
+/** Whether every protected field of `record` holds its real value - opened on this device - rather than its placeholder. */
+export declare function isOpenedRecord(record: SealedRecord | undefined): boolean;
+/** Whether `record` has protected fields. */
+export declare function isProtectedRecord(record: SealedRecord | undefined): boolean;
+/** `records` with every protected one this device can open shown with its real values - only the fields in `only`, when given (a list
+ * shows a contact's name before anyone asks for its phone numbers: each field is one decryption). Never rejects. */
+export declare function openSealedRecords<T extends SealedRecord>(records: T[], only?: readonly string[]): Promise<T[]>;
+/** `der` (a blob the server sealed to `mailboxUid`'s zero-access key, e.g. a protected contact's photo) opened, or `undefined` when this
+ * device can't (the mailbox is locked, or it isn't its key). */
+export declare function openSealedBytes(mailboxUid: string, der: Uint8Array): Promise<Uint8Array | undefined>;
+/**
+ * `input` as written to `shown` - the record the edit started from, as this device showed it: unchanged when `shown` isn't protected.
+ * Otherwise without the protected fields (those `shown.sealedFields` names) whose values are what `shown` has: an opened record's write
+ * sends only what changed, and a placeholder a record that couldn't be opened showed is never sent back as its value. A field of an opened
+ * record that held a value and is emptied is named in `clearedFields`: restapi applies an empty value of a sealed field as a clear only
+ * then (`ZeroAccessRouteSealing.takeClearedFields()`), since an empty placeholder sent back by a client that couldn't open the record would
+ * otherwise wipe the sealed value for good. `opened`: `shown` holds the real values (by default, whether it was opened here).
+ */
+export declare function protectedRecordWrite<T extends object>(shown: SealedRecord | undefined, input: T, opened?: boolean): T;
+/** `openSealedRecords()` for one record. */
+export declare function openSealedRecord<T extends SealedRecord>(record: T, only?: readonly string[]): Promise<T>;

package/dist/lib/zeroAccess/sealedRecords.js

@@ -0,0 +1,136 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Calendar events, contacts and tasks of a mailbox whose zero-access encryption covers their type keep their protected fields only
+ * sealed, field by field, to the mailbox's zero-access key (`sealedFields`; the readable column holds a placeholder - restapi
+ * `specs/search.md` §3 *What It Covers*). They are opened here with the mailbox's unlocked keys; while it is locked a record keeps its
+ * placeholders. The decryption code is loaded only when a sealed record is actually seen.
+ *
+ * Writing needs nothing here: the client sends plaintext and the server seals it on arrival.
+ */
+import { fromBase64 } from "../crypto/encoding.js";
+import { getUnlockedKeys, subscribeKeySession } from "../crypto/keySession.js";
+/** Opened values by sealed text - the same sealed text always opens to the same value. Cleared with `clearSealedRecords()`. */
+const opened = new Map();
+/** Forgets every opened value (a mailbox locking, or the test seam). */
+export function clearSealedRecords() {
+    opened.clear();
+}
+/** Set on a record whose every sealed field was opened. A symbol, so it survives a spread copy (an occurrence of an event) and is never sent. */
+const OPENED = Symbol("openedSealedRecord");
+/** Whether every protected field of `record` holds its real value - opened on this device - rather than its placeholder. */
+export function isOpenedRecord(record) {
+    return !!record && record[OPENED] === true;
+}
+/** Whether `record` has protected fields. */
+export function isProtectedRecord(record) {
+    return !!record?.sealedFields && Object.keys(record.sealedFields).length > 0;
+}
+/** `record` with every sealed field (of `only`, when given) this device can open set to its value; `undefined` when it can't open them
+ * (locked, or not its key). */
+async function openRecord(record, only) {
+    const keys = getUnlockedKeys(record.mailboxUid)?.zeroAccessKeys;
+    if (!keys?.length) {
+        return undefined;
+    }
+    try {
+        const values = {};
+        for (const [name, sealed] of Object.entries(record.sealedFields)) {
+            if (only && !only.includes(name)) {
+                continue;
+            }
+            if (!opened.has(sealed)) {
+                const { decryptEnvelopedDataWithKeys } = await import("../crypto/smime.js");
+                const value = JSON.parse(new TextDecoder().decode(await decryptEnvelopedDataWithKeys(fromBase64(sealed), keys)));
+                // The mailbox locked while this was opened: the lock's clear has already run, so nothing is kept or shown.
+                if (!getUnlockedKeys(record.mailboxUid)) {
+                    return undefined;
+                }
+                opened.set(sealed, value);
+            }
+            values[name] = opened.get(sealed);
+        }
+        return only ? { ...record, ...values } : { ...record, ...values, [OPENED]: true };
+    }
+    catch {
+        return undefined;
+    }
+}
+let watchingKeys = false;
+/** Opened values go when keys are locked (which signing out does), so nothing opened outlives its key session. Subscribed when the
+ * first protected record is opened, not on import. */
+function forgetOnLock() {
+    if (watchingKeys) {
+        return;
+    }
+    watchingKeys = true;
+    subscribeKeySession((event) => {
+        if (event.state === "locked") {
+            clearSealedRecords();
+        }
+    });
+}
+/** `records` with every protected one this device can open shown with its real values - only the fields in `only`, when given (a list
+ * shows a contact's name before anyone asks for its phone numbers: each field is one decryption). Never rejects. */
+export async function openSealedRecords(records, only) {
+    if (!records.some(isProtectedRecord)) {
+        return records;
+    }
+    forgetOnLock();
+    return Promise.all(records.map(async (record) => (isProtectedRecord(record) ? ((await openRecord(record, only)) ?? record) : record)));
+}
+/** `der` (a blob the server sealed to `mailboxUid`'s zero-access key, e.g. a protected contact's photo) opened, or `undefined` when this
+ * device can't (the mailbox is locked, or it isn't its key). */
+export async function openSealedBytes(mailboxUid, der) {
+    const keys = getUnlockedKeys(mailboxUid)?.zeroAccessKeys;
+    if (!keys?.length) {
+        return undefined;
+    }
+    try {
+        const { decryptEnvelopedDataWithKeys } = await import("../crypto/smime.js");
+        const bytes = await decryptEnvelopedDataWithKeys(der, keys);
+        // Locked while it was opened: not handed out.
+        return getUnlockedKeys(mailboxUid) ? bytes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A field's value for comparing what a write sends with what was shown: every empty form (`null`, `undefined`, `""`, `[]`) is one. */
+function comparable(value) {
+    return value === null || value === undefined || value === "" || (Array.isArray(value) && value.length === 0) ? "" : JSON.stringify(value);
+}
+/**
+ * `input` as written to `shown` - the record the edit started from, as this device showed it: unchanged when `shown` isn't protected.
+ * Otherwise without the protected fields (those `shown.sealedFields` names) whose values are what `shown` has: an opened record's write
+ * sends only what changed, and a placeholder a record that couldn't be opened showed is never sent back as its value. A field of an opened
+ * record that held a value and is emptied is named in `clearedFields`: restapi applies an empty value of a sealed field as a clear only
+ * then (`ZeroAccessRouteSealing.takeClearedFields()`), since an empty placeholder sent back by a client that couldn't open the record would
+ * otherwise wipe the sealed value for good. `opened`: `shown` holds the real values (by default, whether it was opened here).
+ */
+export function protectedRecordWrite(shown, input, opened = isOpenedRecord(shown)) {
+    if (!isProtectedRecord(shown)) {
+        return input;
+    }
+    const changes = { ...input };
+    const clearedFields = [];
+    for (const field of Object.keys(shown.sealedFields)) {
+        if (!(field in changes)) {
+            continue;
+        }
+        const value = comparable(changes[field]);
+        if (value === comparable(shown[field])) {
+            delete changes[field];
+        }
+        else if (value === "" && opened) {
+            clearedFields.push(field);
+        }
+    }
+    return (clearedFields.length > 0 ? { ...changes, clearedFields } : changes);
+}
+/** `openSealedRecords()` for one record. */
+export async function openSealedRecord(record, only) {
+    return (await openSealedRecords([record], only))[0];
+}

package/lib/admin/domainsApi.ts

@@ -90,7 +90,7 @@ export function verifyDomain(uid: string, client?: ApiClient): Promise<Domain> {
     return withClient(client, `/mail/domains/${encodeURIComponent(uid)}/verify`, { method: "POST" });
 }
 
-export type DnsRecordType = "ownership" | "mx" | "spf" | "dkim" | "dmarc" | "autodiscover_cname" | "autodiscover_srv";
+export type DnsRecordType = "ownership" | "mx" | "spf" | "dkim" | "dmarc" | "openpgpkey_cname" | "autodiscover_cname" | "autodiscover_srv";
 
 /** One mail-related DNS record this server recommends for a domain, live-checked against real DNS —
  * purely diagnostic, never mutates anything (unlike `verifyDomain`). The two `autodiscover_*` types are only

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