@rapidmx/web-client 0.21.0 → 0.22.0

package/lib/admin/escrowAuditLogApi.ts

@@ -0,0 +1,101 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `EscrowAuditLogEntry` route (`BaseEscrowAuditLogRoute`) — read
+ * only, same posture as `auditLogApi.ts`: `create`/`update`/`delete`/`truncate` unconditionally 403 for
+ * every caller, trusted included (the only writer is restapi's own internal `recordEscrowAuditEntry()`),
+ * so there is no write function here to mirror. `find`/`get` auto-scope to matters under scopes the
+ * caller holds (unfiltered for a trusted admin); `verifyAuditChain()` (`GET /verify`) is
+ * `@RequiresTrustedRole()`-only server-side — this wrapper applies no gating of its own, the server
+ * enforces it and a non-trusted caller simply gets a 403 `ApiRequestError` back.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+/** The lifecycle event an `EscrowAuditLogEntry` records — mirrors `@rapidmx/restapi`'s `EscrowAuditAction`
+ * enum values exactly, including a Matter-scoped eDiscovery export's lifecycle (`matter_export.*`, whose
+ * `requestId` is the `MatterExportRequest` uid). Deliberately excludes a denied access request (nothing was
+ * ever granted or used there); that goes through the ordinary `AuditLogEntry` (`auditLogApi.ts`) instead. */
+export type EscrowAuditAction =
+    | "escrow_access_request.created"
+    | "escrow_access_request.approved"
+    | "matter_export.requested"
+    | "matter_export.ready"
+    | "matter_export.failed"
+    | "escrow_access_request.material_read";
+
+export interface EscrowAuditLogEntry {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    /** Monotonic, global (not per-scope) sequence number. */
+    sequence: number;
+    /** The immediately-preceding entry's `hash` — `undefined` only for the very first entry
+     * (`sequence === 0`). */
+    previousHash?: string;
+    /** Hex digest over this entry's own content plus `previousHash`, computed with `hashAlgorithm`. */
+    hash: string;
+    /** The scheme `hash` was computed with. Absent = a legacy entry verified with plain SHA-256. */
+    hashAlgorithm?: EscrowAuditHashAlgorithm;
+    action: EscrowAuditAction;
+    holderUserUid: string;
+    matterId: string;
+    mailboxUid: string;
+    requestId: string;
+    /** ISO 8601 timestamp. */
+    occurredAt: string;
+    details?: Record<string, unknown>;
+}
+
+/** `client`, given by every function below, 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. */
+export function listAuditLogEntries(params: ListParams = {}, client?: ApiClient): Promise<EscrowAuditLogEntry[]> {
+    return withClient(client, `/escrow/audit-log?${buildQuery(params)}`);
+}
+
+export function getAuditLogEntry(uid: string, client?: ApiClient): Promise<EscrowAuditLogEntry> {
+    return withClient(client, `/escrow/audit-log/${encodeURIComponent(uid)}`);
+}
+
+/** Mirrors `@rapidmx/restapi`'s `EscrowAuditHashAlgorithm` enum values. */
+export type EscrowAuditHashAlgorithm = "sha256" | "hmac-sha256";
+
+/** Why the chain failed verification - mirrors `@rapidmx/restapi`'s `EscrowAuditVerificationFailure`
+ * (`util/EscrowAuditUtils.ts`): `link_mismatch` (an entry deleted/inserted/reordered), `hash_mismatch` (an
+ * entry edited), `unknown_algorithm`, `algorithm_downgrade` (an unkeyed entry after an HMAC one),
+ * `hmac_key_unavailable` (server can't check HMAC entries), `truncated` (entries deleted from the tail),
+ * `head_mismatch`, `head_mac_mismatch` (forged/edited head record), `head_missing`. */
+export type EscrowAuditVerificationFailure =
+    | "link_mismatch"
+    | "hash_mismatch"
+    | "unknown_algorithm"
+    | "algorithm_downgrade"
+    | "hmac_key_unavailable"
+    | "truncated"
+    | "head_mismatch"
+    | "head_mac_mismatch"
+    | "head_missing";
+
+export interface EscrowAuditVerificationResult {
+    valid: boolean;
+    /** The lowest `sequence` at which the chain breaks, if `valid` is `false`. */
+    brokenAtSequence?: number;
+    /** Why the chain is invalid, when `valid` is `false`. A newer server may add values - treat an
+     * unrecognized one as a generic verification failure. */
+    reason?: EscrowAuditVerificationFailure | (string & {});
+}
+
+/** Walks the entire hash chain end to end. `@RequiresTrustedRole()`-only server-side, deliberately not
+ * holder-accessible — the chain is global across every scope, so `brokenAtSequence` would leak the
+ * existence/volume of *other* scopes' escrow activity to a holder who only has standing to know about
+ * their own scope. A non-trusted caller gets a 403 `ApiRequestError`, same as any other gated endpoint. */
+export function verifyAuditChain(client?: ApiClient): Promise<EscrowAuditVerificationResult> {
+    return withClient(client, "/escrow/audit-log/verify");
+}

package/lib/admin/escrowScopesApi.ts

@@ -0,0 +1,112 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `EscrowScope` CRUD route (`BaseEscrowScopeRoute`) —
+ * trusted-role-only for every action (create/update/delete/find/count/findById). Configuring *who counts
+ * as a holder*, the dual-control threshold, and the scope's own public key is an administrative act,
+ * deliberately separate from actually holding the eDiscovery/compliance role (see `mattersApi.ts`,
+ * `specs/end-to-end_encryption.md`'s "Separation of duties") — this file is consumed only by
+ * `apps/admin/escrow-scopes/*`, never by the holder-facing `apps/escrow` area.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+import type { ResolvedPrincipal } from "../mail/mailboxAccessApi.js";
+
+export type { ListParams };
+export type { ResolvedPrincipal };
+
+/** A scope's own public key — mirrors `@rapidmx/restapi`'s `EscrowScopePublicKey` exactly. An admin
+ * pastes in the fields of an already-issued certificate here; nothing in this app generates a keypair. */
+export interface EscrowScopePublicKey {
+    /** Base64-encoded public key (DER-encoded X.509 certificate, or raw key material). */
+    publicKey: string;
+    type: string;
+    /** SHA-256 fingerprint of the key, hex encoded. */
+    fingerprint: string;
+    /** UTC timestamp (epoch ms) at which this key becomes valid. */
+    notBefore: number;
+    /** UTC timestamp (epoch ms) at which this key expires. */
+    notAfter: number;
+    /** UTC timestamp (epoch ms) at which this key was revoked, if applicable. */
+    revokedAt?: number;
+}
+
+export interface EscrowScope {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    name: string;
+    description?: string;
+    publicKey: EscrowScopePublicKey;
+    /** Uids of every user in the eDiscovery/compliance role for this scope. At least one required. */
+    holderUserUids: string[];
+    /** M in "M-of-N dual control" — must be between 1 and `holderUserUids.length` inclusive. */
+    requiredHolders: number;
+    notifySubjectOnAccess: boolean;
+}
+
+/** `client`, given by every function below, 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. */
+export function listEscrowScopes(params: ListParams = {}, client?: ApiClient): Promise<EscrowScope[]> {
+    return withClient(client, `/escrow/scopes?${buildQuery(params)}`);
+}
+
+/**
+ * Who a typed principal - a mailbox address, an auth-server username or e-mail alias, or a user uid - is, for the
+ * escrow-scope admin screen to confirm before adding them to `holderUserUids`. Rejects with a 404 `ApiRequestError`
+ * ("No user found for ...") for nobody. Trusted-role-only (`BaseEscrowScopeRoute.resolveHolder()` in
+ * `@rapidmx/restapi`) - never weaker than `createEscrowScope()`/`updateEscrowScope()`'s own gate on this same field.
+ */
+export function resolveEscrowScopeHolder(principal: string, client?: ApiClient): Promise<ResolvedPrincipal> {
+    return withClient(client, `/escrow/scopes/resolve-holder?principal=${encodeURIComponent(principal)}`);
+}
+
+export function getEscrowScope(uid: string, client?: ApiClient): Promise<EscrowScope> {
+    return withClient(client, `/escrow/scopes/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateEscrowScopeInput {
+    name: string;
+    description?: string;
+    publicKey: EscrowScopePublicKey;
+    holderUserUids: string[];
+    requiredHolders: number;
+    notifySubjectOnAccess?: boolean;
+}
+
+export function createEscrowScope(input: CreateEscrowScopeInput, client?: ApiClient): Promise<EscrowScope> {
+    return withClient(client, "/escrow/scopes", {
+        method: "POST",
+        body: JSON.stringify({ notifySubjectOnAccess: false, ...input }),
+    });
+}
+
+export interface UpdateEscrowScopeInput {
+    uid: string;
+    version: number;
+    name?: string;
+    description?: string;
+    publicKey?: EscrowScopePublicKey;
+    holderUserUids?: string[];
+    requiredHolders?: number;
+    notifySubjectOnAccess?: boolean;
+}
+
+export function updateEscrowScope(input: UpdateEscrowScopeInput, client?: ApiClient): Promise<EscrowScope> {
+    return withClient(client, `/escrow/scopes/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+/** 409s if a `Matter` still references this scope (`BaseEscrowScopeRoute.delete()`'s own referencing-Matter
+ * guard) — the caller is expected to surface that `ApiRequestError` as-is, same as every other CRUD wrapper
+ * in this package. */
+export function deleteEscrowScope(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/escrow/scopes/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/lib/admin/leftoverMailboxApi.ts

@@ -0,0 +1,120 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over what `@rapidmx/restapi` offers for the data a deleted mailbox leaves behind. Deleting a mailbox removes
+ * only the mailbox itself: its folders and everything in them stay, and a new mailbox at the same address is refused (409)
+ * until that data is erased. An administrator (a trusted role AND an elevated session, like every admin-console call) lists
+ * what is left (`listLeftoverMailboxes()`) and erases it (`eraseLeftoverMailbox()`), which files an already approved erasure
+ * request that the server's `ErasureExecutionJob` then runs - poll it with `getErasureRequest()` (`erasureRequestApi.ts`).
+ * The erasure is irreversible; a legal hold on the address makes the server refuse it (409, its message names the matter).
+ */
+import { ApiClient, ApiRequestError, withClient } from "../util/api.js";
+import type { DataSubjectErasureRequest, DataSubjectErasureStatus } from "../mail/erasureRequestApi.js";
+
+/** The newest erasure request filed for a leftover address. */
+export interface LeftoverErasure {
+    uid: string;
+    status: DataSubjectErasureStatus;
+    dateCreated: string;
+}
+
+/** A deleted mailbox that still has data. */
+export interface LeftoverMailbox {
+    /** The deleted mailbox's uid - its address. */
+    mailboxUid: string;
+    /** Folders it still has (trashed ones included). */
+    folderCount: number;
+    /** Messages it still has (trashed ones included). */
+    messageCount: number;
+    /** The newest erasure request filed for the address, when there is one. */
+    erasure?: LeftoverErasure;
+}
+
+/** One page of `listLeftoverMailboxes()`. */
+export interface LeftoverMailboxPage {
+    items: LeftoverMailbox[];
+    /** Pass as `after` to continue; absent at the end of the list. */
+    next?: string;
+}
+
+export interface LeftoverMailboxListParams {
+    /** At most this many (the server's default is 50 and its ceiling 100). */
+    limit?: number;
+    /** Continue after this mailbox uid - a previous page's `next`. */
+    after?: string;
+}
+
+/** `client`, given by every function below, 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. */
+
+/** Lists the deleted mailboxes that still have data, sorted by address. Administrators only (403 otherwise). */
+export function listLeftoverMailboxes(params: LeftoverMailboxListParams = {}, client?: ApiClient): Promise<LeftoverMailboxPage> {
+    const query = new URLSearchParams();
+    if (params.limit !== undefined) {
+        query.set("limit", String(params.limit));
+    }
+    if (params.after !== undefined) {
+        query.set("after", params.after);
+    }
+    const suffix = query.toString();
+    return withClient(client, `/mail/mailboxes/leftover${suffix ? `?${suffix}` : ""}`);
+}
+
+/**
+ * Erases what the deleted mailbox `mailboxUid` (its address) left behind - permanently. Answers the erasure request, already
+ * approved; it runs in the background, so poll `getErasureRequest()` until its status is `completed` (or `denied`). Repeating
+ * the call returns the request already filed. Rejects with 409 while a legal hold covers the address (the message names the
+ * matter) or when a mailbox exists at the address (a live mailbox is never erased this way), and with 404 when nothing is left.
+ */
+export function eraseLeftoverMailbox(mailboxUid: string, client?: ApiClient): Promise<DataSubjectErasureRequest> {
+    return withClient(client, `/mail/erasure-requests/leftover`, {
+        method: "POST",
+        body: JSON.stringify({ mailboxUid }),
+    });
+}
+
+/** Why creating a mailbox at an address was refused because of the data a deleted mailbox left there. */
+export type LeftoverConflict =
+    | {
+          /** The data is still there: erasing it (`eraseLeftoverMailbox()`) is the way out. */
+          reason: "mailbox-data-remaining";
+          mailboxUid?: string;
+      }
+    | {
+          /** An erasure of it is approved or running and has not finished: wait for it (poll `erasure.uid`). */
+          reason: "mailbox-data-erasing";
+          mailboxUid?: string;
+          erasure: { uid: string; status: DataSubjectErasureStatus };
+      };
+
+/**
+ * What `error` says about leftover data, when it is the 409 that `createMailbox()` answers for an address whose deleted mailbox
+ * still has data - `undefined` for any other error. Read defensively: the server's body is untrusted data, and an error from
+ * before the server said why (no `reason`) is not recognised.
+ */
+export function leftoverConflictOf(error: unknown): LeftoverConflict | undefined {
+    if (!(error instanceof ApiRequestError) || error.status !== 409) {
+        return undefined;
+    }
+    const body = error.details as { reason?: unknown; mailboxUid?: unknown; erasure?: { uid?: unknown; status?: unknown } } | undefined;
+    const mailboxUid = typeof body?.mailboxUid === "string" ? body.mailboxUid : undefined;
+    if (body?.reason === "mailbox-data-remaining") {
+        return { reason: "mailbox-data-remaining", mailboxUid };
+    }
+    if (body?.reason === "mailbox-data-erasing" && typeof body.erasure?.uid === "string" && typeof body.erasure.status === "string") {
+        return {
+            reason: "mailbox-data-erasing",
+            mailboxUid,
+            erasure: { uid: body.erasure.uid, status: body.erasure.status as DataSubjectErasureStatus },
+        };
+    }
+    return undefined;
+}
+
+/** Whether an erasure request is no longer going to change: it finished or was refused. */
+export function isErasureSettled(status: DataSubjectErasureStatus): boolean {
+    return status === "completed" || status === "denied";
+}

package/lib/admin/mailboxPolicyApi.ts

@@ -0,0 +1,38 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s deployment-wide `MailboxPolicy` singleton (`BaseMailboxPolicyRoute`,
+ * mounted at `system/mailbox-policy`). `GET` is readable by any authenticated user and always returns the values in
+ * effect (server config fills anything never saved), along with the server's current config values for the same
+ * fields as `defaults`; `PUT` is trusted-admin-only.
+ */
+import { ApiClient, withClient } from "../util/api.js";
+
+/** Mirrors `@rapidmx/restapi`'s `PublicMailboxPolicy`. */
+export interface MailboxPolicy {
+    /** The quota a newly created mailbox starts with, in bytes. */
+    defaultQuotaBytes: number;
+    /** Whether a signed-in user without a mailbox may create their own on first sign-in. */
+    autoProvisionEnabled: boolean;
+    /** The quota of a mailbox a user creates for themselves, in bytes. */
+    autoProvisionQuotaBytes: number;
+    /**
+     * What the server's config says for each field right now - what a "reset" puts it back to. Absent from a server
+     * that predates it, in which case there is nothing to reset to.
+     */
+    defaults?: Omit<MailboxPolicy, "defaults">;
+}
+
+/** `client`, given by every function below, 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. */
+export function getMailboxPolicy(client?: ApiClient): Promise<MailboxPolicy> {
+    return withClient(client, "/system/mailbox-policy");
+}
+
+/** Partial patch - only supplied fields change. */
+export function updateMailboxPolicy(patch: Partial<Omit<MailboxPolicy, "defaults">>, client?: ApiClient): Promise<MailboxPolicy> {
+    return withClient(client, "/system/mailbox-policy", { method: "PUT", body: JSON.stringify(patch) });
+}

package/lib/admin/matterExportApi.ts

@@ -0,0 +1,62 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s eDiscovery Matter export (`BaseMatterExportRequestRoute`,
+ * mounted at `escrow/matter-export-requests`) — holder-gated throughout (`requireEscrowHolder()` against
+ * the matter's own `escrowScopeId`), never admin-gated. Lives under `admin/` only because that's where
+ * every other Matter/Escrow-family wrapper in this package lives (see `mattersApi.ts`'s own doc
+ * comment) — consumed exclusively by `apps/escrow`. Export runs asynchronously (restapi's own
+ * `MatterExportJob`, not this client) — `createMatterExportRequest()` only stages a `pending` request;
+ * poll `listMatterExportRequests()` for `status` to become `"ready"` (or `"failed"`).
+ */
+import { ApiClient, apiUrl, withClient } from "../util/api.js";
+import { RequestListParams, buildRequestListQuery } from "../util/apiQuery.js";
+
+export type { RequestListParams };
+
+export type MatterExportStatus = "pending" | "processing" | "ready" | "failed";
+
+export interface MatterExportRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    matterId: string;
+    requestedByUserUid: string;
+    status: MatterExportStatus;
+    blobKey?: string;
+    errorMessage?: string;
+    /** How many times the server job has claimed this request into `"processing"` (a stalled claim is reclaimed
+     * back to `"pending"` until the job's max attempts, then marked `"failed"`). */
+    processingAttempts?: number;
+}
+
+/** `client`, given by every function below that isn't a plain URL builder, 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. */
+export function createMatterExportRequest(matterId: string, client?: ApiClient): Promise<MatterExportRequest> {
+    return withClient(client, `/escrow/matter-export-requests`, {
+        method: "POST",
+        body: JSON.stringify({ matterId }),
+    });
+}
+
+/** Scoped server-side to matters under scopes the caller holds — never all requests, even for a trusted
+ * admin who isn't also a holder. Newest first; `params` pages through them (`limit` capped at 500
+ * server-side) and/or narrows to one `matterId`. */
+export function listMatterExportRequests(params: RequestListParams = {}, client?: ApiClient): Promise<MatterExportRequest[]> {
+    return withClient(client, `/escrow/matter-export-requests${buildRequestListQuery(params)}`);
+}
+
+export function getMatterExportRequest(uid: string, client?: ApiClient): Promise<MatterExportRequest> {
+    return withClient(client, `/escrow/matter-export-requests/${encodeURIComponent(uid)}`);
+}
+
+/** A plain URL, not a fetch wrapper — same "let the browser download it natively" pattern
+ * `dataExportApi.ts`'s `exportRequestDownloadUrl()` already establishes. 404s until `status === "ready"`. */
+export function matterExportRequestDownloadUrl(uid: string): string {
+    return apiUrl(`/escrow/matter-export-requests/${encodeURIComponent(uid)}/download`);
+}

package/lib/admin/matterSearchApi.ts

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s eDiscovery Matter-scoped search (`BaseMatterSearchRoute`,
+ * mounted at `escrow/matter-search`) — holder-gated (`requireEscrowHolder()` against the matter's own
+ * `escrowScopeId`). Lives under `admin/` only because that's where every other Matter/Escrow-family
+ * wrapper in this package lives — consumed exclusively by `apps/escrow`.
+ *
+ * Reuses the exact same query-param grammar/shape `search/searchApi.ts`'s own `search()` already speaks
+ * (`SearchParams`/`buildSearchParams()`) — this route is a fan-out of the same underlying
+ * `SearchProvider`, once per the matter's own custodian mailboxes, not a new search capability. `before`/
+ * `after` are always clamped server-side to the matter's own date range, regardless of what's supplied.
+ * There is no merged cross-mailbox ranking or cursor-based pagination — the response is keyed by
+ * `mailboxUid`, one page per custodian, matching how a holder-facing review UI groups results anyway.
+ */
+import { ApiClient, withClient } from "../util/api.js";
+import { SearchParams, SearchResultPage, buildSearchParams } from "../search/searchApi.js";
+
+export type { SearchParams, SearchResultPage };
+
+/** `client`, given below, 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), this behaves exactly as before. */
+export function searchMatter(
+    matterId: string,
+    text: string,
+    params: SearchParams = {},
+    client?: ApiClient,
+): Promise<Record<string, SearchResultPage>> {
+    const query = buildSearchParams(text, params);
+    query.set("matterId", matterId);
+    return withClient(client, `/escrow/matter-search?${query.toString()}`);
+}

package/lib/admin/mattersApi.ts

@@ -0,0 +1,86 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `Matter` CRUD route (`BaseMatterRoute`) — deliberately
+ * **holder-gated, not admin-gated**, unlike every other file in `admin/`: a trusted administrator who
+ * isn't a holder of the matter's own `escrowScopeId` gets the same 403 as anyone else (see
+ * `escrowScopesApi.ts`, `specs/end-to-end_encryption.md`'s "Separation of duties"). Lives under `admin/`
+ * only because that's where every other CRUD-wrapper module in this package lives, not because it's an
+ * admin-only feature — it's consumed exclusively by `apps/escrow`, never `apps/admin`.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+export interface Matter {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    name: string;
+    description?: string;
+    /** Immutable after creation — see `BaseMatterRoute.update()`. */
+    escrowScopeId: string;
+    custodianMailboxUids: string[];
+    /** ISO 8601 timestamp. */
+    dateRangeStart: string;
+    /** ISO 8601 timestamp. */
+    dateRangeEnd: string;
+    /** Once set, this matter is permanently closed — one-way, see `closeMatter()`. */
+    closedAt?: string;
+}
+
+/** `client`, given by every function below, 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. */
+export function listMatters(params: ListParams = {}, client?: ApiClient): Promise<Matter[]> {
+    return withClient(client, `/escrow/matters?${buildQuery(params)}`);
+}
+
+export function getMatter(uid: string, client?: ApiClient): Promise<Matter> {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateMatterInput {
+    name: string;
+    description?: string;
+    escrowScopeId: string;
+    custodianMailboxUids: string[];
+    dateRangeStart: string;
+    dateRangeEnd: string;
+}
+
+export function createMatter(input: CreateMatterInput, client?: ApiClient): Promise<Matter> {
+    return withClient(client, "/escrow/matters", { method: "POST", body: JSON.stringify(input) });
+}
+
+export interface UpdateMatterInput {
+    uid: string;
+    version: number;
+    name?: string;
+    description?: string;
+    custodianMailboxUids?: string[];
+    dateRangeStart?: string;
+    dateRangeEnd?: string;
+}
+
+export function updateMatter(input: UpdateMatterInput, client?: ApiClient): Promise<Matter> {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteMatter(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+
+/** One-way — `BaseMatterRoute.close()` 400s if the matter is already closed, and once closed no further
+ * `updateMatter()`/`createAccessRequest()` against it will succeed. */
+export function closeMatter(uid: string, client?: ApiClient): Promise<Matter> {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(uid)}/close`, { method: "POST" });
+}