@rapidmx/web-client 0.20.0 → 0.22.0

package/dist/lib/admin/escrowAccessRequestsApi.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `EscrowAccessRequest` route (`BaseEscrowAccessRequestRoute`) —
+ * a bespoke (non-`CRUDRoute`) route: no `update`/`delete`/`count`, and `create()` only ever accepts
+ * `{matterId, mailboxUid}` (everything else is derived server-side). Holder-gated throughout, same as
+ * `mattersApi.ts`. `find()`/`findById()` auto-scope to matters under scopes the caller holds; `approve()`/
+ * `deny()` mutate in place and return the updated request; `material()` is only ever readable once the
+ * request is `approved`/`fulfilled`, and returns still-encrypted `MasterKeyWraps` this server can't
+ * decrypt either — see `EscrowAccessMaterial`'s own doc comment.
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams, RequestListParams } from "../util/apiQuery.js";
+export type { ListParams, RequestListParams };
+export interface EscrowAccessRequestApproval {
+    holderUserUid: string;
+    /** ISO 8601 timestamp. */
+    approvedAt: string;
+}
+export type EscrowAccessRequestStatus = "pending" | "approved" | "denied" | "fulfilled";
+export interface EscrowAccessRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    matterId: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    approvals: EscrowAccessRequestApproval[];
+    /** Snapshotted from `EscrowScope.requiredHolders` at creation time — see this type's own restapi doc
+     * comment on why it's never re-read live. */
+    requiredHoldersAtCreation: number;
+    status: EscrowAccessRequestStatus;
+    /** Set the first time `getAccessRequestMaterial()` is successfully called — informational only. */
+    fulfilledAt?: string;
+    deniedByUserUid?: string;
+    deniedAt?: string;
+}
+/** Mirrors `@rapidmx/restapi`'s `MasterKeyWrap` — same shape `crypto/keyvaultApi.ts` already defines for
+ * the mailbox-owner side of this feature, duplicated here rather than cross-imported (same convention
+ * every other `*Api.ts` wrapper in this package already follows for overlapping wire shapes). */
+export interface MasterKeyWrap {
+    method: "password" | "passkey" | "recovery" | "escrow";
+    methodId?: string;
+    escrowScopeId?: string;
+    ciphertext: string;
+    nonce: string;
+    salt: string;
+    kdf: string;
+    schemeVersion: number;
+    createdAt: number;
+}
+/** The wire shape `getAccessRequestMaterial()` returns — only ever the escrow-method wraps scoped to the
+ * matter's own escrow scope, never `wrappedKeys` or any other unlock method. This app deliberately never
+ * attempts to decrypt these — they're surfaced as-is for the holder to copy into their own offline
+ * tooling, per `specs/end-to-end_encryption.md`'s "this server never holds the scope's private key". */
+export interface EscrowAccessMaterial {
+    masterKeyWraps: MasterKeyWrap[];
+}
+/** `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. */
+/** Newest first. Every request belongs to one Matter, so `params.matterId` narrows the list to that
+ * Matter's requests (still only ever within scopes the caller holds). */
+export declare function listAccessRequests(params?: RequestListParams, client?: ApiClient): Promise<EscrowAccessRequest[]>;
+export declare function getAccessRequest(uid: string, client?: ApiClient): Promise<EscrowAccessRequest>;
+export interface CreateAccessRequestInput {
+    matterId: string;
+    mailboxUid: string;
+}
+/** The requester's own creation counts as their first approval — auto-approved immediately if
+ * `EscrowScope.requiredHolders` is `1`. */
+export declare function createAccessRequest(input: CreateAccessRequestInput, client?: ApiClient): Promise<EscrowAccessRequest>;
+/** 409s if the request isn't `pending`; 400s if the caller already approved it. */
+export declare function approveAccessRequest(uid: string, client?: ApiClient): Promise<EscrowAccessRequest>;
+/** 409s if the request isn't `pending`. */
+export declare function denyAccessRequest(uid: string, client?: ApiClient): Promise<EscrowAccessRequest>;
+/** 403s ("Dual control threshold not yet met.") unless the request is `approved`/`fulfilled`. Marks the
+ * request `fulfilled` server-side as a side effect of a successful call, and records an
+ * `EscrowAuditAction.MATERIAL_READ` entry — see `escrowAuditLogApi.ts`. */
+export declare function getAccessRequestMaterial(uid: string, client?: ApiClient): Promise<EscrowAccessMaterial>;

package/dist/lib/admin/escrowAccessRequestsApi.js

@@ -0,0 +1,46 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `EscrowAccessRequest` route (`BaseEscrowAccessRequestRoute`) —
+ * a bespoke (non-`CRUDRoute`) route: no `update`/`delete`/`count`, and `create()` only ever accepts
+ * `{matterId, mailboxUid}` (everything else is derived server-side). Holder-gated throughout, same as
+ * `mattersApi.ts`. `find()`/`findById()` auto-scope to matters under scopes the caller holds; `approve()`/
+ * `deny()` mutate in place and return the updated request; `material()` is only ever readable once the
+ * request is `approved`/`fulfilled`, and returns still-encrypted `MasterKeyWraps` this server can't
+ * decrypt either — see `EscrowAccessMaterial`'s own doc comment.
+ */
+import { withClient } from "../util/api.js";
+import { buildQuery } from "../util/apiQuery.js";
+/** `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. */
+/** Newest first. Every request belongs to one Matter, so `params.matterId` narrows the list to that
+ * Matter's requests (still only ever within scopes the caller holds). */
+export function listAccessRequests(params = {}, client) {
+    const { matterId, ...paging } = params;
+    return withClient(client, `/escrow/access-requests?${buildQuery(paging, matterId ? { matterId } : {})}`);
+}
+export function getAccessRequest(uid, client) {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}`);
+}
+/** The requester's own creation counts as their first approval — auto-approved immediately if
+ * `EscrowScope.requiredHolders` is `1`. */
+export function createAccessRequest(input, client) {
+    return withClient(client, "/escrow/access-requests", { method: "POST", body: JSON.stringify(input) });
+}
+/** 409s if the request isn't `pending`; 400s if the caller already approved it. */
+export function approveAccessRequest(uid, client) {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}/approve`, { method: "POST" });
+}
+/** 409s if the request isn't `pending`. */
+export function denyAccessRequest(uid, client) {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}/deny`, { method: "POST" });
+}
+/** 403s ("Dual control threshold not yet met.") unless the request is `approved`/`fulfilled`. Marks the
+ * request `fulfilled` server-side as a side effect of a successful call, and records an
+ * `EscrowAuditAction.MATERIAL_READ` entry — see `escrowAuditLogApi.ts`. */
+export function getAccessRequestMaterial(uid, client) {
+    return withClient(client, `/escrow/access-requests/${encodeURIComponent(uid)}/material`);
+}

package/dist/lib/admin/escrowAuditLogApi.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 } from "../util/api.js";
+import { ListParams } 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 declare function listAuditLogEntries(params?: ListParams, client?: ApiClient): Promise<EscrowAuditLogEntry[]>;
+export declare function getAuditLogEntry(uid: string, client?: ApiClient): Promise<EscrowAuditLogEntry>;
+/** 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 declare function verifyAuditChain(client?: ApiClient): Promise<EscrowAuditVerificationResult>;

package/dist/lib/admin/escrowAuditLogApi.js

@@ -0,0 +1,31 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { withClient } from "../util/api.js";
+import { buildQuery } from "../util/apiQuery.js";
+/** `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 = {}, client) {
+    return withClient(client, `/escrow/audit-log?${buildQuery(params)}`);
+}
+export function getAuditLogEntry(uid, client) {
+    return withClient(client, `/escrow/audit-log/${encodeURIComponent(uid)}`);
+}
+/** 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) {
+    return withClient(client, "/escrow/audit-log/verify");
+}

package/dist/lib/admin/escrowScopesApi.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 } from "../util/api.js";
+import { ListParams } 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 declare function listEscrowScopes(params?: ListParams, client?: ApiClient): Promise<EscrowScope[]>;
+/**
+ * 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 declare function resolveEscrowScopeHolder(principal: string, client?: ApiClient): Promise<ResolvedPrincipal>;
+export declare function getEscrowScope(uid: string, client?: ApiClient): Promise<EscrowScope>;
+export interface CreateEscrowScopeInput {
+    name: string;
+    description?: string;
+    publicKey: EscrowScopePublicKey;
+    holderUserUids: string[];
+    requiredHolders: number;
+    notifySubjectOnAccess?: boolean;
+}
+export declare function createEscrowScope(input: CreateEscrowScopeInput, client?: ApiClient): Promise<EscrowScope>;
+export interface UpdateEscrowScopeInput {
+    uid: string;
+    version: number;
+    name?: string;
+    description?: string;
+    publicKey?: EscrowScopePublicKey;
+    holderUserUids?: string[];
+    requiredHolders?: number;
+    notifySubjectOnAccess?: boolean;
+}
+export declare function updateEscrowScope(input: UpdateEscrowScopeInput, client?: ApiClient): Promise<EscrowScope>;
+/** 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 declare function deleteEscrowScope(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/admin/escrowScopesApi.js

@@ -0,0 +1,50 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { withClient } from "../util/api.js";
+import { buildQuery } from "../util/apiQuery.js";
+/** `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 = {}, client) {
+    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, client) {
+    return withClient(client, `/escrow/scopes/resolve-holder?principal=${encodeURIComponent(principal)}`);
+}
+export function getEscrowScope(uid, client) {
+    return withClient(client, `/escrow/scopes/${encodeURIComponent(uid)}`);
+}
+export function createEscrowScope(input, client) {
+    return withClient(client, "/escrow/scopes", {
+        method: "POST",
+        body: JSON.stringify({ notifySubjectOnAccess: false, ...input }),
+    });
+}
+export function updateEscrowScope(input, client) {
+    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, version, client) {
+    return withClient(client, `/escrow/scopes/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/dist/lib/admin/leftoverMailboxApi.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 } 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 declare function listLeftoverMailboxes(params?: LeftoverMailboxListParams, client?: ApiClient): Promise<LeftoverMailboxPage>;
+/**
+ * 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 declare function eraseLeftoverMailbox(mailboxUid: string, client?: ApiClient): Promise<DataSubjectErasureRequest>;
+/** 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 declare function leftoverConflictOf(error: unknown): LeftoverConflict | undefined;
+/** Whether an erasure request is no longer going to change: it finished or was refused. */
+export declare function isErasureSettled(status: DataSubjectErasureStatus): boolean;

package/dist/lib/admin/leftoverMailboxApi.js

@@ -0,0 +1,67 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { ApiRequestError, withClient } from "../util/api.js";
+/** `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 = {}, client) {
+    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, client) {
+    return withClient(client, `/mail/erasure-requests/leftover`, {
+        method: "POST",
+        body: JSON.stringify({ mailboxUid }),
+    });
+}
+/**
+ * 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) {
+    if (!(error instanceof ApiRequestError) || error.status !== 409) {
+        return undefined;
+    }
+    const body = error.details;
+    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 },
+        };
+    }
+    return undefined;
+}
+/** Whether an erasure request is no longer going to change: it finished or was refused. */
+export function isErasureSettled(status) {
+    return status === "completed" || status === "denied";
+}

package/dist/lib/admin/mailboxPolicyApi.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 } 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 declare function getMailboxPolicy(client?: ApiClient): Promise<MailboxPolicy>;
+/** Partial patch - only supplied fields change. */
+export declare function updateMailboxPolicy(patch: Partial<Omit<MailboxPolicy, "defaults">>, client?: ApiClient): Promise<MailboxPolicy>;

package/dist/lib/admin/mailboxPolicyApi.js

@@ -0,0 +1,21 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { withClient } from "../util/api.js";
+/** `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) {
+    return withClient(client, "/system/mailbox-policy");
+}
+/** Partial patch - only supplied fields change. */
+export function updateMailboxPolicy(patch, client) {
+    return withClient(client, "/system/mailbox-policy", { method: "PUT", body: JSON.stringify(patch) });
+}

package/dist/lib/admin/matterExportApi.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 } from "../util/api.js";
+import { RequestListParams } 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 declare function createMatterExportRequest(matterId: string, client?: ApiClient): Promise<MatterExportRequest>;
+/** 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 declare function listMatterExportRequests(params?: RequestListParams, client?: ApiClient): Promise<MatterExportRequest[]>;
+export declare function getMatterExportRequest(uid: string, client?: ApiClient): Promise<MatterExportRequest>;
+/** 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 declare function matterExportRequestDownloadUrl(uid: string): string;

package/dist/lib/admin/matterExportApi.js

@@ -0,0 +1,39 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { apiUrl, withClient } from "../util/api.js";
+import { buildRequestListQuery } from "../util/apiQuery.js";
+/** `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, client) {
+    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 = {}, client) {
+    return withClient(client, `/escrow/matter-export-requests${buildRequestListQuery(params)}`);
+}
+export function getMatterExportRequest(uid, client) {
+    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) {
+    return apiUrl(`/escrow/matter-export-requests/${encodeURIComponent(uid)}/download`);
+}