@rapidmx/web-client 0.35.0 → 0.37.0

package/lib/mail/mailApi.ts

@@ -26,7 +26,7 @@ import {
 } from "../util/api.js";
 import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 import { deviceTimeZone } from "../util/timeZone.js";
-import type { EncryptionPreference, PublicKey } from "../crypto/keyvaultApi.js";
+import type { EncryptionPreference, PublicKey, ZeroAccessKey } from "../crypto/keyvaultApi.js";
 import { bytesToBinaryString } from "../crypto/mime.js";
 import { EMBEDDED_IMAGE_TYPES, newContentId, parseDataImage } from "./inlineImages.js";
 import { MAX_QUOTED_IMAGE_BYTES } from "./compose/quotedImages.js";
@@ -129,6 +129,18 @@ export interface Mailbox {
      * per the spec's own `PublicKey` doc comment. Absent/empty means no keys enrolled yet
      * (`KeyEnrollmentGate` handles that state). */
     keys?: PublicKey[];
+    /** The mailbox's zero-access certificates, managed by the server (never written by a client). Read them from
+     * `KeyVault.zeroAccessKeys` to unlock; here only so a settings page can tell whether one is enrolled. */
+    zeroAccessKeys?: ZeroAccessKey[];
+    /** "Enable zero-access encryption": unset means on. Only the mailbox's owner can change it - restapi drops anybody
+     * else's value. Has no effect while the server's `EncryptionPolicy.allowZeroAccess` is off. */
+    zeroAccessEnabled?: boolean;
+    /** Which data types zero-access encryption covers - see `ZeroAccessTypes`. Owner only. */
+    zeroAccessTypes?: ZeroAccessTypes;
+    /** The ActiveSync and Outlook clients that sync this mailbox, as the server last saw them. Server-written. */
+    syncClients?: SyncClients;
+    /** When the owner last exported a zero-access key for a phone or Outlook. Server-written. */
+    zeroAccessKeysExportedAt?: number;
     /** How the caller reaches this mailbox: `"owner"` (theirs) or `"delegate"` (shared with them). Set by the plain list and read of
      * mailboxes - not in an administration-scope answer - so a client can label the shared ones; see `isSharedWithMe()`. */
     accessRole?: "owner" | "delegate";
@@ -257,6 +269,19 @@ export function autoProvisionMailbox(
  * `null` clears them - `JSON.stringify()` drops an `undefined` value entirely, which would instead leave
  * the old value in place.
  */
+/** The data types zero-access encryption can cover (restapi `specs/search.md` §3 *What It Covers*). */
+export type ZeroAccessDataType = "mail" | "calendar" | "contacts" | "tasks";
+
+/** `Mailbox.zeroAccessTypes`: per data type, whether zero-access covers it. A type left out is undecided: mail counts as on, the others
+ * as off, until the server decides them from the owner's devices. */
+export type ZeroAccessTypes = Partial<Record<ZeroAccessDataType, boolean>>;
+
+/** `Mailbox.syncClients`: the ActiveSync devices (each with the data types it syncs) and Outlook. */
+export interface SyncClients {
+    activesync?: { devices: { id: string; model?: string; types: ZeroAccessDataType[]; lastSeenAt: number }[] };
+    mapi?: { lastSeenAt: number };
+}
+
 export interface UpdateMailboxInput {
     uid: string;
     version: number;
@@ -281,6 +306,12 @@ export interface UpdateMailboxInput {
     autoSendReceiptsInternal?: boolean;
     autoSendReceiptsFederated?: boolean;
     autoSendReceiptsExternal?: boolean;
+    /** Owner-only server-side (anybody else's value is dropped) - see `Mailbox.zeroAccessEnabled`. */
+    zeroAccessEnabled?: boolean;
+    /** Owner-only server-side; a partial choice is merged into the stored one - see `Mailbox.zeroAccessTypes`. */
+    zeroAccessTypes?: ZeroAccessTypes;
+    /** The mailbox's own encryption preference, replaced whole - see `Mailbox.encryptPreference`. */
+    encryptPreference?: EncryptionPreference;
     /** Trusted-caller-only server-side. `null` (or `""`) unassigns the mailbox's escrow scope; the
      * referenced `EscrowScope` must exist otherwise. See `Mailbox.escrowScopeId`. */
     escrowScopeId?: string | null;
@@ -594,6 +625,10 @@ export interface Message {
      * stored body, not from a flag this API exposes. Always present on a real `Message` (defaults
      * `false` server-side), same optional-for-old-fixtures caveat as `Mailbox.oofEnabled`. */
     encrypted?: boolean;
+    /** Set when the server sealed this message at rest on arrival (zero-access, restapi `specs/search.md` §3): its stored body is an
+     * S/MIME message only the mailbox's zero-access key opens, `subject` is `[...]` and `bodyPreview` empty - the real ones are in
+     * `sealedSummary`. */
+    zeroAccess?: { keyFingerprint: string; sealedSummary: string };
     /** The raw RFC 2369/8058 `List-Unsubscribe` header value, if present — computed server-side by
      * `@rapidmx/restapi`'s `ScanPipeline` from the stored MIME, the strongest single bulk-mail signal it
      * captures. Used client-side to detect list traffic when replying, per
@@ -797,7 +832,7 @@ export type MessageReportKind = "junk" | "phishing" | "not_junk";
 /** Why the server did not teach its spam filter from a report: `encrypted` (it has no plaintext to teach), `disabled` (learning is switched off),
  * `unsupported` (no spam engine, or one that cannot learn), `too_large` (over the size it reads) or `failed` (the engine could not be reached,
  * refused, or the message could not be read). The report itself still happened. */
-export type MessageLearnSkipped = "encrypted" | "disabled" | "unsupported" | "too_large" | "failed";
+export type MessageLearnSkipped = "encrypted" | "zero_access" | "disabled" | "unsupported" | "too_large" | "failed";
 
 /** What `reportMessage()` answers. */
 export interface MessageReportResult {
@@ -820,6 +855,9 @@ export interface ReportMessageOptions {
     /** With `not_junk` only (else a 400): also add the message's From address to the mailbox's safe senders. Needs full access to the mailbox (403 otherwise,
      * before anything is done). */
     alwaysTrustSender?: boolean;
+    /** For a zero-access message only (else a 400): its original source, base64-encoded, decrypted here - the server holds only the sealed
+     * copy, so this is what its spam filter learns from (never stored). Without it the server skips learning (`learnSkipped: "zero_access"`). */
+    rawMessage?: string;
 }
 
 /**
@@ -837,7 +875,11 @@ export function reportMessage(
 ): Promise<MessageReportResult> {
     return withClient(client, `/mail/messages/${encodeURIComponent(uid)}/report`, {
         method: "POST",
-        body: JSON.stringify({ kind, ...(options.alwaysTrustSender ? { alwaysTrustSender: true } : {}) }),
+        body: JSON.stringify({
+            kind,
+            ...(options.alwaysTrustSender ? { alwaysTrustSender: true } : {}),
+            ...(options.rawMessage ? { rawMessage: options.rawMessage } : {}),
+        }),
     });
 }
 
@@ -1073,8 +1115,21 @@ export interface AssembleDraftInput {
     bcc?: ComposeRecipientInput[];
     subject?: string;
     html: string;
+    /** See `AssembleIntent`. */
+    intent?: AssembleIntent;
+    /** The addresses this copy is delivered to, when not all of `to`/`cc`/`bcc`: one copy of a message sent in two end-to-end
+     * formats (an S/MIME and an OpenPGP copy, each listing every recipient) goes only to the recipients of its own format. Each
+     * must be one of the recipients. */
+    deliverTo?: string[];
 }
 
+/**
+ * Why a draft is being assembled (server `ComposeIntent`). `"save"`, the default, keeps an edit: in a zero-access mailbox the server
+ * stores it sealed, which it can't send. `"send"` is the assemble right before `sendMessage()`/`queueMessageSend()`: stored readable
+ * until it is relayed, then sealed as the Sent Items copy.
+ */
+export type AssembleIntent = "save" | "send";
+
 /** What a draft records about the thread it belongs to - see `createDraft()`. */
 export interface DraftThreading {
     /** The `messageId` of the message being replied to (`Message.inReplyTo`). */
@@ -1266,6 +1321,8 @@ export interface AssembleDraftRawInput {
      * `crypto/smimeMessage.ts`'s `buildSignedOnlyMessage()`/`buildEncryptedMessage()`, combined with
      * the outer envelope headers (`From`/`To`/`Cc`/`Date`/`Message-ID`/`MIME-Version`) by the caller. */
     rawMime: string;
+    /** See `AssembleIntent`. */
+    intent?: AssembleIntent;
 }
 
 /**

package/lib/mail/mailboxImportApi.ts

@@ -11,6 +11,7 @@
  */
 import { ApiClient, withClient, withClientRaw } from "../util/api.js";
 import { RequestListParams, buildRequestListQuery } from "../util/apiQuery.js";
+import type { Mailbox } from "./mailApi.js";
 
 export type { RequestListParams };
 
@@ -79,3 +80,26 @@ export function listImportRequests(params: RequestListParams = {}, client?: ApiC
 export function getImportRequest(uid: string, client?: ApiClient): Promise<MailboxImportRequest> {
     return withClient(client, `/mail/mailbox-import-requests/${encodeURIComponent(uid)}`);
 }
+
+/** Why server-side import is refused for a mailbox whose mail is zero-access (restapi answers such an upload 409). */
+export const ZERO_ACCESS_IMPORT_MESSAGE =
+    "Importing an archive isn't available while zero-access encryption protects this mailbox's mail: the server would have to keep " +
+    "the uploaded archive readable until the import ran, which zero-access encryption doesn't allow.";
+
+/**
+ * Whether `mailbox`'s mail is stored zero-access encrypted, so restapi refuses a server-side import into it (`specs/search.md` §3: the
+ * uploaded archive would wait readable in the blob store). Decided as restapi's `zeroAccessStatus()` decides it for mail: the
+ * administrator's "Allow zero-access encryption" (`allowZeroAccess`; unknown counts as allowed, so an import is never offered only to be
+ * refused), the owner's switch (unset is on), mail among the protected types (undecided is on), and a key that isn't revoked.
+ */
+export function mailIsZeroAccess(
+    mailbox: Pick<Mailbox, "zeroAccessEnabled" | "zeroAccessTypes" | "zeroAccessKeys">,
+    allowZeroAccess: boolean | undefined,
+): boolean {
+    return (
+        allowZeroAccess !== false &&
+        mailbox.zeroAccessEnabled !== false &&
+        mailbox.zeroAccessTypes?.mail !== false &&
+        (mailbox.zeroAccessKeys ?? []).some((key) => !key.revokedAt)
+    );
+}

package/lib/search/zeroAccessIndexApi.ts

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

package/lib/tasks/tasksApi.ts

@@ -7,6 +7,8 @@
 
 import { ApiClient, withClient } from "../util/api.js";
 import { ListParams, SETTINGS_LIST_LIMIT, buildQuery } from "../util/apiQuery.js";
+import { guardSealedMove } from "../zeroAccess/sealedMoves.js";
+import { protectedRecordWrite } from "../zeroAccess/sealedRecords.js";
 
 export type TaskPriority = "low" | "normal" | "high";
 
@@ -31,6 +33,9 @@ export interface Task {
     myDay?: boolean;
     /** The uid of the user this task is assigned to, if any. */
     assignedTo?: string;
+    /** The title and notes sealed to the mailbox's zero-access key while it protects tasks (`title` is then a placeholder) - opened with
+     * `openSealedRecords()`. Server-written. */
+    sealedFields?: Record<string, string> | null;
 }
 
 /** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
@@ -78,13 +83,22 @@ export interface UpdateTaskInput {
     taskListUid?: string;
     myDay?: boolean;
     assignedTo?: string;
+    /** A move to another mailbox, with `folderUid` there - refused for a protected task (`SealedMoveError`). */
+    mailboxUid?: string;
+    folderUid?: string;
 }
 
-export function updateTask(input: UpdateTaskInput, client?: ApiClient): Promise<Task> {
-    return withClient(client, `/mail/tasks/${encodeURIComponent(input.uid)}`, {
-        method: "PUT",
-        body: JSON.stringify(input),
-    });
+/** Saves `input`. One moving the task to another mailbox (`mailboxUid`) is refused with `SealedMoveError` when the task is protected -
+ * before sending anything when `current` (the task as this device has it) says so, else from the server's refusal. With `current`, a
+ * protected task's sealed fields go only when they changed from it, and an emptied one is named in `clearedFields` when `current` was
+ * opened here (`protectedRecordWrite()`). */
+export function updateTask(input: UpdateTaskInput, client?: ApiClient, current?: Task): Promise<Task> {
+    return guardSealedMove(current, input.mailboxUid, () =>
+        withClient<Task>(client, `/mail/tasks/${encodeURIComponent(input.uid)}`, {
+            method: "PUT",
+            body: JSON.stringify(protectedRecordWrite(current, input)),
+        }),
+    );
 }
 
 /** Toggles a task's `completed` flag in place — same pattern as `mailApi.ts`'s `setMessageRead`. */

package/lib/util/clientPlatform.ts

@@ -0,0 +1,50 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * What kind of client this is, for work that should prefer one over another - the search index's week compaction, which a phone
+ * should leave to a computer (restapi `specs/search.md` §8 *Who compacts*).
+ *
+ * - `"desktop"`: a native app on a computer (`tauri-client`, `electron-client`), which installs `window.rapidmx`.
+ * - `"mobile"`: a native app on a phone or tablet (the host sets `window.rapidmx.formFactor: "mobile"`), or a phone or tablet browser.
+ * - `"web"`: any other browser.
+ */
+export type ClientPlatform = "desktop" | "web" | "mobile";
+
+interface NavigatorHints {
+    userAgent?: string;
+    userAgentData?: { mobile?: boolean };
+    connection?: { type?: string; saveData?: boolean };
+}
+
+const MOBILE_USER_AGENT = /Android|iPhone|iPad|iPod|Mobile/i;
+
+function navigatorHints(): NavigatorHints | undefined {
+    return typeof navigator === "undefined" ? undefined : navigator;
+}
+
+/** Whether this browser runs on a phone or tablet, by its User-Agent Client Hints, else its user agent string. */
+function isMobileBrowser(): boolean {
+    const hints = navigatorHints();
+    if (typeof hints?.userAgentData?.mobile === "boolean") {
+        return hints.userAgentData.mobile;
+    }
+    return MOBILE_USER_AGENT.test(hints?.userAgent ?? "");
+}
+
+/** This client's platform (see the module comment). */
+export function clientPlatform(): ClientPlatform {
+    const host = typeof window === "undefined" ? undefined : (window as { rapidmx?: { formFactor?: string } }).rapidmx;
+    if (host) {
+        return host.formFactor === "mobile" ? "mobile" : "desktop";
+    }
+    return isMobileBrowser() ? "mobile" : "web";
+}
+
+/** Whether the connection is one to spare: cellular, or the user asked to save data (Network Information API, where the browser
+ * has it - absent, the connection is taken as unconstrained). */
+export function isConstrainedConnection(): boolean {
+    const connection = navigatorHints()?.connection;
+    return connection?.saveData === true || connection?.type === "cellular";
+}

package/lib/videoconf/protectedMeetings.ts

@@ -0,0 +1,221 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 type { ApiClient } from "../util/api.js";
+import { getVideoMeeting, updateVideoMeeting, type VideoMeetingDetail, type VideoMeetingInvitee } 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 * 60_000;
+
+/** 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 * 60_000;
+
+/** What `createVideoMeeting()` sends to protect a meeting. */
+export interface MeetingProtectionInput {
+    meetingKey: { certificate: string };
+    keyExpiresAt: string;
+    keyWraps: { mailboxUid: string; recipientFingerprint: string; kind: "meeting-key"; cms: string }[];
+    sealedFields: { title: string };
+}
+
+/** A protected meeting's fields, as the server returns them to its organizer. */
+export interface ProtectedMeetingFields {
+    keyProtected?: boolean | null;
+    keyWraps?: { mailboxUid: string; recipientFingerprint: string; kind: string; cms: string }[] | null;
+    /** When the meeting key is discarded (ISO). */
+    keyExpiresAt?: string | null;
+}
+
+/** 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<string, { mailboxUid: string; fragment: string | null }>();
+
+/** Forgets every opened meeting key (sign-out, or the test seam). */
+export function clearMeetingKeys(): void {
+    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: string, mailboxUid: string, fragment: string | null): void {
+    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: string): string | null | undefined {
+    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: Date, now: number = Date.now()): Date {
+    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: string): { certDer: Uint8Array; fingerprint: string; privateKey: CryptoKey } | undefined {
+    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: string,
+    title: string,
+    invitees: VideoMeetingInvitee[],
+    expiresAt: Date,
+): Promise<{ protection: MeetingProtectionInput; invitees: { email: string; sealedFields?: { displayName: string } }[]; fragment: string } | undefined> {
+    const organizer = organizerKey(mailboxUid);
+    if (!organizer) {
+        return undefined;
+    }
+    const key = await generateMeetingKey(expiresAt);
+    const seal = async (value: unknown): Promise<string> =>
+        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: string, fragment: string | null, mailboxUid: string): void {
+    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: VideoMeetingDetail & ProtectedMeetingFields): Promise<string | undefined> {
+    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: VideoMeetingDetail & ProtectedMeetingFields): Promise<string | null> {
+    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: { videoMeetingUid?: string | null; attendees?: { address: string }[]; organizer?: { address: string } },
+    client?: ApiClient,
+): Promise<Record<string, string> | undefined> {
+    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: Record<string, string> = {};
+        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: string, endDate: Date, client?: ApiClient): Promise<void> {
+    try {
+        if (fragments.get(meetingUid)?.fragment === null) {
+            return;
+        }
+        const meeting: VideoMeetingDetail & ProtectedMeetingFields = 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()) < 60_000)) {
+            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);
+    }
+}