@rapidmx/web-client 0.10.0 → 0.11.0

package/README.md

@@ -119,10 +119,185 @@ How it behaves:
   names are unchanged (`useShortcutProps()` gives a control both).
 
 Known limits: a browser keeps a few keys for itself (`Ctrl+N`, `Ctrl+T`, `Ctrl+W` are never delivered to a page, and some browsers claim
-`Ctrl+Shift+A/B/C/M/S`); and a message body is shown in a sandboxed iframe, which forwards no key events, so after clicking into a
-message body press Tab or click the list before using a shortcut. In the compose body the editor's own bindings win over `Ctrl+Shift+S`, `B`
+`Ctrl+Shift+A/B/C/M/S`); a message body is shown in a frame of its own, which hands the keys pressed in it on to the layer, so they work there too. In the compose body the editor's own bindings win over `Ctrl+Shift+S`, `B`
 and `L` (strike-through, quote, align left).
 
+## The reading pane
+
+`shared/components/mail/` draws a message as a **card** and a conversation as a stack of them, under a **subject card** that stays pinned at the top
+while the cards scroll (`MessageDetailPane`, `ConversationThreadPane`, and `reading/` for the pieces):
+
+- **Subject card** - the conversation's (or the message's) subject as the page's `h1`, "N messages", a note when a very long thread was cut. In a
+  thread it is on screen at once, from what the list row already knows, with a skeleton card per message (up to three) until the messages arrive.
+- **Message card** - rounded, bordered and lifted, in the app's own tokens (`bg-surface`, `text-text`, `border-border`), so it follows the theme, a
+  branding palette and the Appearance colours. A header row with the sender's initials, `Name <address>`, To/Cc/Bcc, the time and the actions (Reply,
+  Reply All, Forward, Archive, Move to, Labels, and "View original" when it applies); the security badge and every notice (signature, key change,
+  receipts, Outbox state); attachments; the body; a slim "You replied to this message." bar; and, on a single message and on the newest open one in a
+  thread, Reply and Forward at its foot. An older message of a thread is a collapsed card (sender, date, first line) that expands on click or Enter
+  (`aria-expanded`, `aria-controls`; the focus stays on the message's header button as it swaps between the two states).
+- **Each card is exactly as tall as its message.** The body is shown at its natural height - no inner scrollbar, no dead space, no fixed height - and
+  follows it as images load and the width changes. A table or image wider than the card scrolls **inside** the card and never widens the pane. The
+  pane scrolls as a whole. Everything is on screen before the body: the header card, the message card's header and a skeleton where the body will be.
+
+- **Encrypted messages** are themed card content in the same place as the body, never a frame: while the security state is being worked out, a skeleton;
+  locked (no unlocked keys on this device), a lock, "This message is encrypted", "Unlock your keys to read it" and an **Unlock** button that asks for the unlock
+  prompt and, once unlocked - by it or from anywhere - decrypts the message in place and moves the focus to it; unreadable with the keys in hand (not a recipient,
+  damaged), "This message can’t be decrypted" with the reason and no button; decrypted, the message like any other. The placeholder subject `[...]` reads
+  "Encrypted message", and list rows and collapsed cards with no preview say "Encrypted message" with a small lock.
+
+**How a body is shown.** The server sanitizes a message's HTML when it ingests it (`GET /mail/messages/:id/content`); the client then treats what it
+receives - and everything it recovers by decrypting or verifying, which the server never saw - as hostile. It is sanitized again with DOMPurify (scripts,
+event handlers, `javascript:` URLs, every remote resource), stripped of forms, frames, media, plug-ins, SVG's active elements and every link that is not
+`http(s)`/`mailto`/`tel`, and shown in a **sandboxed iframe without `allow-scripts`**, behind a Content-Security-Policy that allows no script, object, frame,
+form or fetch (images are `data:` URIs and this server's own attachment URLs for inline `cid:` images; **remote images are never loaded**). `allow-same-origin`
+is what lets the app measure the frame and adapt its colours, and it is safe only because nothing can run there: any one of the four layers (server
+sanitizer, client sanitizer, CSP, sandbox) stops a script on its own - see `.claude/NOTES.md`, 2026-09-21, for the threat model and the hostile-mail corpus it
+was tried against. Every link opens in a new tab without an opener. A message over 1.5 MB of markup or 20,000 elements is offered on its own page instead.
+
+**Mail takes the theme.** A message follows the app's scheme wherever its author left the colours to the reader, and is shown as authored where the
+author chose them. Plain-text mail and HTML with no colours at all (a typed reply) are drawn in the theme's surface and text colours, links in its link
+colour. Where the HTML sets a colour: text on the theme's surface is kept if it reads (4.5:1) and adapted if it doesn't (black becomes white in a dark
+theme, white becomes dark in a light one, a low-contrast navy is only lightened as far as it takes); anything on an authored, opaque background - a white table,
+a banner, a gradient - is shown exactly as authored, except text nobody coloured, which gets black or white by contrast with that background, never the theme's
+colour. A message that declares its own dark styles (a `color-scheme` meta or property, or a `prefers-color-scheme: dark` block) gets them when the theme is
+dark. "View original" (the sun, in the card's header; the moon then goes back) shows just that message exactly as authored for the rest of the session; it is
+offered only where adapting changes something. Known limits: a dark logo or PNG with a transparent background on a dark theme, text baked into images,
+`mix-blend-mode` and SVG paint are left as they are.
+
+Printing puts a message back to the colours it was written with for the print and adapts it again afterwards; the actions and the footer are not printed.
+
+## Notifications, sending and the Outbox
+
+**One pop-up system** (`shared/notifications/`). `AppChrome` mounts `NotificationCenter` once, right under the header row (a zero-height `sticky`
+line that sticks just below the header - the title bar's or a branding header's height, published as `--rr-header-h` - so the stack starts below the
+account menu and never covers it, the header's buttons or a compose window's title bar and Send button; its height is capped by `--rr-compose-top`), and
+everything the app has to say goes through the framework-free store:
+
+```ts
+import { notify, update, dismiss } from "@rapidmx/web-client/shared/notifications/store.js";
+import { notifyApiError } from "@rapidmx/web-client/shared/notifications/apiErrors.js";
+
+const id = notify({ kind: "error", title: "Couldn't archive the message", message: "The server said no.",
+                    details: ["Status: 502 (api-1)"], actions: [{ label: "Retry", onClick: retry }], dedupeKey: "archive" });
+update(id, { kind: "success", title: "Archived", actions: [] });   // resolve it
+try { await archive(); } catch (err) { notifyApiError(err, "Couldn't archive the message"); }
+```
+
+`kind` is `mail`, `info`, `success`, `warning` or `error`. At most three show at once (the rest queue); errors and anything with `actions` are sticky
+until dismissed or resolved by `update()`/`dismiss()`, the others go after 5 to 10 seconds - clocks pause on hover, focus and a hidden tab; a repeated
+`dedupeKey` is one pop-up with a count; errors are announced assertively (`role="alert"` inside an `aria-live="assertive"` region), the rest politely;
+`details` is an expandable, monospace, copyable block. The last 30 (not new-mail ones) are kept in memory and `sessionStorage` and listed by "Recent
+notifications" in the account menu. `notifyApiError()` turns an `ApiRequestError` into an error pop-up with the server's message (a `401` becomes
+"Your session expired" with a Sign in button, anywhere in the app: the frame registers `setApiUnauthorizedObserver()`). The frame also catches unhandled
+errors and rejections as one "Something went wrong", and says so, subtly, when the live connection has been down for more than ten seconds.
+
+**Sending does not wait** (`shared/mail/outbox/`). Send validates what it can from what the window knows (a recipient, keys that must be unlocked, an
+attachment that can't be signed - shown inline, the window stays open; an attachment still uploading is waited for), then closes the window at once and
+hands a snapshot to `startSend()`: save, sign or encrypt in the browser if that applies, then `POST /mail/messages/:id/send` with `{ "background": true }`,
+which answers `202 { status: "queued", message }` and relays in the background. Failures at any stage are a sticky "This message wasn't sent" with the
+reason, technical details, **Retry** and **Open draft**; the server's later outcome arrives as `send-succeeded` / `send-retrying` / `send-failed` push
+events. The Outbox row in the folder list is a pill with the count (optimistic at the click, then the server's), animated while anything is on its way and
+red while one failed; rows in the Outbox list say what each message is doing.
+
+**Encryption fails open.** A message is treated as unencrypted - its draft saves, Close and Send work, nothing about encryption is shown - unless you turned
+encryption on (or replied to an encrypted message) or the encryption policy *was loaded* and encrypts for every recipient; a request that failed, is slow or
+is pending never blocks anything (`compose/encryptionRequirement.ts`).
+
+## The header, the footer and their variables
+
+The admin console's Branding page sets a **header** and a **footer** as HTML. The server sanitizes them when they are saved and this client
+sanitizes them again when it shows them: no scripts, styles, forms, inputs or SVG, no `on*` handlers, only `http`, `https` and `mailto` links.
+
+**A custom header is the top of the app.** When one is set it replaces the app's own title bar (the app's name and the account menu) and the icon
+at the top of the icon rail: the rail then starts with the app icons, and the header stays at the top of the window while a page scrolls. The
+account menu moves into it. Two variables can be written in the *text* of the header or the footer:
+
+| Variable | Replaced with |
+| --- | --- |
+| `{USER_MENU}` | The account menu: the avatar button and its drop-down (Account, Settings, notifications, keyboard shortcuts, Admin Console, Sign Out). |
+| `{APP_TITLE}` | The name of the app on screen ("Mail", "Calendar", "Contacts", "Tasks", "Settings"), kept current as you move between apps without a page load. |
+
+```html
+<div style="display:flex; align-items:center; justify-content:space-between; padding:0.5rem 1rem">
+    <span>{APP_TITLE}</span>
+    <span>{USER_MENU}</span>
+</div>
+```
+
+- A variable is matched exactly - upper case, in braces, no spaces - and only in text. One in an attribute (`title="{USER_MENU}"`), a comment,
+  a `<script>` or `<style>` is left as written or gone with them, and the author can't write the placeholders React fills in (`data-rr-slot` is
+  stripped).
+- `{USER_MENU}` is replaced **once**, where it first appears in the header; if the header has none, at its first place in the footer (the menu then
+  opens upward); if neither has one, the menu sits in a small cell at the right end of the header, so the account menu, Sign Out and the shortcuts
+  help are never lost. A second or third copy is removed (two menus would mean duplicate ids and focus targets), and so is one inside a link or in
+  text that can't hold an element (`<title>`, `<textarea>`).
+- `{APP_TITLE}` is replaced **everywhere** it appears, as text (never markup). It changes on client-side navigation, and works in the footer too.
+- The menu is drawn into `<body>` with `position: fixed`, so a header with `overflow: hidden`, its own `z-index` or a stacking context can neither
+  clip it nor hide it behind the page. It follows its button when the window resizes or scrolls, and fits a 390 px window.
+- Put `{USER_MENU}` where your CSS doesn't hide it: a header whose stylesheet hides its `<nav>` on phones should keep the variable outside the nav.
+- Focus order is document order: the menu button is reached after the text before it and before what follows it.
+- Pages that don't use a shell (the booking pages) render `BrandingHeader` and `BrandingFooter`, which have no menu: `{USER_MENU}` renders nothing
+  there and `{APP_TITLE}` is the `appTitle` prop, if any. The variable names are `USER_MENU_VARIABLE` and `APP_TITLE_VARIABLE` in
+  `shared/components/layout/BrandingChrome.js`.
+
+The frame draws the header from the `branding` prop the server rendered the page with (`useBranding()`'s own fetch takes over when it answers), so
+the frame is the right shape - no title bar, no rail icon - from the first paint, and the icon of a frame without a custom header sits flush with the
+top of the window (`RailIcon`: it is measured on a canvas and raised by whatever empty margin the image file has above its artwork).
+
+## Appearance
+
+**Settings > Appearance** (`/settings/appearance`) lets each user choose the colour scheme (System, Light or Dark), four theme colours (primary,
+accent, surface and text - each a colour picker with a hex field and its own "Reset"), and a background (none, a colour, or an uploaded picture with
+dim 0-80%, blur 0-20 px and fit cover, contain or tile). Every change is applied to the real app in the same frame - the page you are on is the preview -
+and saved in the background (coalesced, only what changed); a save that fails puts the change back and says so. A picture is checked before it is
+uploaded (PNG, JPEG, WebP or AVIF, up to 8 MB). Text on the surface, and text on an accent button, under 4.5:1 contrast gets a warning, never a block.
+"Reset all" returns everything to the defaults and removes the picture.
+
+**How it reaches the app.** `AppearanceProvider` (mounted by `AppChrome`, `AdminShell` and `EscrowShell`) owns the preferences and writes one
+`<style id="rr-appearance">` into `<head>` (`appearance/theme.js`), sets `<html data-theme="light|dark">` (for System, the operating system's scheme,
+live) and remembers the result in `localStorage` (`rapidmx-appearance`). The server's `_layout.tsx` renders the same stylesheet from the `appearance`
+page prop and a tiny inline script (`APPEARANCE_BOOT_SCRIPT`) applies the browser's copy before the first paint, so there is no flash on a load and none
+on a client-side navigation. The server caches a rendered page for up to a minute, so whichever copy - the page's or the browser's - was changed last wins,
+and the server is asked once the page is up.
+
+- **Precedence:** the app's defaults < the deployment's branding stylesheet < the user's choices. A user's colours are `--rr-color-*` custom properties
+  declared `!important` on `<html>`, so no branding rule can beat them; the branding stylesheet's own rules (say a header's background) still decide their
+  own elements, exactly as before. Only the colours a user chose are set: primary and accent get their full scales (darker and lighter steps mixed from the
+  one colour) and readable text colours, surface and text get their alt, border and muted derivatives.
+- **The background** is two fixed pseudo-elements of `<html>` (`::before` the picture or colour, `::after` the dim, the scheme's surface colour at the
+  chosen opacity), behind everything, with no markup, no layout shift and nothing to repaint while a list scrolls. With a background set the icon rail, the
+  header and the content region become translucent panels (`--color-surface` and `--color-surface-alt` are the surface colour at an alpha, chosen so text
+  and muted text stay at least 4.5:1 against the worst place the picture can be - the picture's lightest and darkest twentieth, measured on a canvas -
+  more see-through for a plain photo or a high dim, more opaque for a busy one); menus, dialogs, drawers and pop-ups take the opaque colours back. Without a
+  background nothing changes.
+- **Hooks:** `useResolvedTheme()` (`appearance/resolvedTheme.js`) is `"light"` or `"dark"`, live, needing no provider; `useAppearance()` gives
+  `{ prefs, resolved, setPrefs(patch), uploadBackground(file), removeBackground(), reset(), saving, error, ... }`.
+- **API** (`@rapidmx/react-shared/appearance/preferencesApi.js`): `GET/PUT /mail/preferences/appearance` (a merge), `POST/DELETE
+  /mail/preferences/appearance/background`, `GET .../background/:version`; a change is also pushed as `AppearancePreferences...` `update` events on
+  the user's own uid channel.
+
+## Toolbars, folders and the signing certificate
+
+**Toolbars that fit (`components/layout/ResponsiveToolbar.tsx`).** A bar measures its own width (`ResizeObserver`) and lays itself out from a table of actions (`ToolbarAction`: label,
+icon, group, `rank` - the lowest goes into "More" first - and `essential`): captions under the icons while everything fits; else icons only (each keeps a tooltip and, for New contact, its
+shortcut's `title` and `aria-keyshortcuts`); else as many icons as fit and the rest in a portalled `role="menu"` behind a **More** button. `layoutToolbar(actions, width)` is the pure
+function behind it (`width === undefined` - server render, no ResizeObserver - shows everything), and the bar is `overflow-x-clip` so it can never paint over the pane beside it. Contacts
+uses it; the panes around it follow one rule: a list column of `clamp(16rem, 32vw, 26rem)`, a detail pane that keeps the rest, each column scrolling by itself (`md:h-[calc(100dvh - var(--rr-header-h))]` on the
+page root - the frame's own height is open-ended), the side menu a drawer below `lg`, and no empty shell column for a single mailbox.
+
+**The folder tree (`mail/folderTree.ts`).** `FOLDER_ORDER` (Inbox, Drafts, Outbox, Sent Items, Deleted Items, Junk, Archive, then custom), `upsertFolder()`, `removeFolder()` and
+`reconcileFolders()` return the same array when nothing changed (everything that reads the tree starts over when it is a new one), never touch the counts (the overlay in `folderCounts.ts`
+owns them) and never remove on a listing (deletions arrive as events). `useMailConnection()` files what `Folder` create / update / delete events say and what every counts read-back lists
+(`useFolderCounts(mailboxes, folders, onFoldersListed)`), so a folder is found by an event, a message in it, a send outcome, the poll, a focus or a reconnect, whichever comes first. `folderRows()`
+is the one place a folder that has not arrived is drawn - a muted Outbox / Sent Items placeholder while a message is on its way - so it can never be drawn twice. Push channels are ordered inboxes,
+mailbox uids, then the other folders in sidebar order (`pushChannelsFor()`).
+
+**The signing certificate (`signing/`).** `enrollmentTracker.ts` follows one enrollment per mailbox for everybody who wants to show or react to it: a first read, then 15 s, 30 s and every 60 s
+while pending - only while the page is visible (a hidden tab asks nothing; coming back or a focus asks at once and restarts the backoff), stopping when it ends; `checkEnrollmentNow()` is the
+"Check status" (a 10 s cooldown, the server's 429 honoured, a plain read on a server without the check endpoint); a pending enrollment stays followed after the page that started it is left.
+`useSigningEnrollmentWatcher()` (in `AppChrome`) seeds it for the mailboxes you own and raises the "issued" / "failed" pop-up. `enrollmentView.ts` holds the wording, the steps, the percentage
+and the expiry maths; `SigningCertificateCard` draws them. The account menu's **Theme** row is `ThemeSwitch`, over `useAppearance().setPrefs({ mode })`.
+
 ## Plugin UI surface
 
 Server plugins can ship their own pages (see the plugin manifest's `ui` field in `@rapidmx/restapi`). The server builds
@@ -182,6 +357,12 @@ use:
 - `components/overlays/Modal.js` and `components/overlays/Drawer.js`;
 - `components/pickers/MiniDatePicker.js`.
 
+## Uninstalling a plugin with its data
+
+The admin console's Plugins page (`PluginsManager`, also embedded in the setup wizard) uninstalls a plugin through a dialog with an unchecked **Also delete all data this plugin stored** box. Ticking it lists what will be deleted (collections and tables, saved settings, cached package and pages, whatever the plugin cleans up itself), says **This can't be undone**, turns the confirm button into the red **Uninstall and delete data** and keeps it disabled until the plugin's display name is typed (case and surrounding spaces ignored). The dialog is a `Modal` (focus moves in and stays in, Escape closes, the checkbox is described by the list) and a `<form>`, so Enter in the name field confirms once it matches; at 390 px it keeps the modal's 20 px gutters and the list wraps.
+
+The request is `removePlugin(uid, { purgeData: true })` (`@rapidmx/react-shared/admin/pluginsApi.js`); the server accepts it only from an elevated administrator, and an `api-104` answer is shown as a request to reload or sign in again. Deletion happens on the servers after the last copy stops running the plugin, so `GET /api/system/plugins/status` carries each deletion as `purges` and the page lists the uninstalled plugin with its state - *Uninstalled - data will be deleted after servers restart* (and how many servers still run it), *Data deleted <date>*, or *Data deletion failed: <reason>* with the failed steps and a Retry button. It reads the status every 5 seconds while a deletion is waiting or running, and raises an `apps/shared/notifications` pop-up when one that was under way is deleted or fails, and a warning when adding a plugin cancels one. A plugin that is installed is never shown as uninstalled, whatever the server still lists about an earlier deletion.
+
 ## Development
 
 ```sh

package/apps/admin/_layout.tsx

@@ -4,15 +4,20 @@
 ///////////////////////////////////////////////////////////////////////////////
 import React, { PropsWithChildren } from "react";
 import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+import { AppearanceHead, appearanceHtmlAttributes } from "../shared/appearance/AppearanceHead.js";
 import { CUSTOM_STYLESHEET_LINK_ID } from "@rapidmx/react-shared/branding/useBranding.js";
 
 export interface LayoutProps {
     /** See `apps/www/_layout.tsx`'s `LayoutProps` doc comment - identical mechanism, supplied by
      * `AdminConsoleRoute`'s `fetchProps()` override. */
     branding?: Branding;
+    /** The signed-in user's stored appearance preferences (a page prop from the same `fetchProps()`, present only on the www pages and only when the user has any): rendered as a stylesheet in the `<head>` so the very first paint is themed - see `AppearanceHead`. */
+    appearance?: unknown;
+    /** The signed-in user (supplied by the framework), so a cached appearance from another account on this browser is never applied. */
+    userUid?: string;
 }
 
-export default function Layout({ children, branding }: PropsWithChildren<LayoutProps>) {
+export default function Layout({ children, branding, appearance, userUid }: PropsWithChildren<LayoutProps>) {
     const title = branding?.title || branding?.companyName
         ? `${branding?.title || branding?.companyName}: Mail Admin Console`
         : "RapidMX: Mail Admin Console";
@@ -20,7 +25,7 @@ export default function Layout({ children, branding }: PropsWithChildren<LayoutP
     const stylesheetHref = branding?.stylesheetUrl;
 
     return (
-        <html lang="en">
+        <html lang="en" {...appearanceHtmlAttributes(appearance, userUid)}>
             <head>
                 <meta charSet="utf-8" />
                 <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -34,6 +39,7 @@ export default function Layout({ children, branding }: PropsWithChildren<LayoutP
                     href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"
                 />
                 {stylesheetHref && <link rel="stylesheet" href={stylesheetHref} id={CUSTOM_STYLESHEET_LINK_ID} />}
+                <AppearanceHead appearance={appearance} />
             </head>
             <body>{children}</body>
         </html>

package/apps/admin/index.tsx

@@ -31,7 +31,8 @@ function MailboxesListContent() {
     useEffect(() => {
         setLoading(true);
         setError(null);
-        listMailboxes({ page, limit: PAGE_SIZE })
+        // The administration scope: every mailbox as administrative metadata - the console never shows anybody's mail.
+        listMailboxes({ page, limit: PAGE_SIZE, scope: "admin" })
             .then(setMailboxes)
             .catch((err) => setError(err instanceof ApiRequestError ? err.message : "Could not load mailboxes."))
             .finally(() => setLoading(false));
@@ -69,6 +70,11 @@ function MailboxesListContent() {
                 </div>
             </div>
 
+            <p className="text-sm text-text-muted mb-4">
+                Administrative details only (addresses, owners, quota). The console never shows a mailbox&rsquo;s mail:
+                to see someone&rsquo;s account, impersonate them from their mailbox page.
+            </p>
+
             {error && <Alert>{error}</Alert>}
 
             <Modal open={confirmingSetup} onClose={() => setConfirmingSetup(false)} title="Run setup again?">

package/apps/admin/ingest-queue/index.tsx

@@ -50,7 +50,8 @@ function IngestQueueContent() {
         let cancelled = false;
         setLoading(true);
         setError(null);
-        listIngestQueue(mailboxUid, { page, limit: PAGE_SIZE })
+        // The administration scope: any mailbox's pending mail, recorded in the audit log.
+        listIngestQueue(mailboxUid, { page, limit: PAGE_SIZE, scope: "admin" })
             .then((data) => {
                 if (!cancelled) setEntries(data);
             })

package/apps/admin/mailboxes/[uid].tsx

@@ -23,12 +23,16 @@ function formatBytes(bytes: number): string {
 export default function MailboxDetailPage(props: Omit<AdminShellProps, "active"> & { params: { uid: string } }) {
     return (
         <AdminShell {...props} active="mailboxes">
-            <MailboxDetailContent uid={props.params.uid} impersonationBaseUrl={props.impersonationBaseUrl} />
+            <MailboxDetailContent uid={props.params.uid} impersonationBaseUrl={props.impersonationBaseUrl} currentUserUid={props.userUid} />
         </AdminShell>
     );
 }
 
-function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & Pick<AdminShellProps, "impersonationBaseUrl">) {
+function MailboxDetailContent({
+    uid,
+    impersonationBaseUrl,
+    currentUserUid,
+}: { uid: string; currentUserUid?: string } & Pick<AdminShellProps, "impersonationBaseUrl">) {
     const [mailbox, setMailbox] = useState<Mailbox | null>(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);
@@ -47,7 +51,7 @@ function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & P
         setAccessError(null);
     }
 
-    // Only ever invoked from the access-confirmation modal below, which only renders for a loaded mailbox that has
+    // Only ever invoked from the impersonation-confirmation modal below, which only renders for a loaded mailbox that has
     // an owner. A failure stays in the modal rather than replacing the whole page.
     async function handleAccessMailbox() {
         setImpersonating(true);
@@ -56,7 +60,7 @@ function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & P
             await impersonateUser(impersonationBaseUrl ?? "", mailbox!.ownerUserUid!);
             window.location.href = "/";
         } catch (err) {
-            setAccessError(err instanceof ApiRequestError ? err.message : "Could not access this mailbox.");
+            setAccessError(err instanceof ApiRequestError ? err.message : "Could not impersonate this user.");
             setImpersonating(false);
         }
     }
@@ -86,7 +90,8 @@ function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & P
     useEffect(() => {
         setLoading(true);
         setError(null);
-        getMailbox(uid)
+        // The administration scope: administrative metadata only - the console never shows a mailbox's mail or settings.
+        getMailbox(uid, { scope: "admin" })
             .then(setMailbox)
             .catch((err) => setError(err instanceof ApiRequestError ? err.message : "Could not load this mailbox."))
             .finally(() => setLoading(false));
@@ -114,7 +119,7 @@ function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & P
                 <div className="flex gap-3 shrink-0">
                     {mailbox.ownerUserUid && (
                         <Button type="button" variant="secondary" className="!w-auto" onClick={() => setConfirmingAccess(true)}>
-                            Access this mailbox
+                            Impersonate this user
                         </Button>
                     )}
                     <Button
@@ -128,6 +133,13 @@ function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & P
                 </div>
             </div>
 
+            <p className="text-sm text-text-muted">
+                The console shows administrative details only - never a mailbox&rsquo;s mail or settings.
+                {mailbox.ownerUserUid
+                    ? " To see this mailbox as its owner sees it, impersonate them: that is recorded, and you can stop at any time."
+                    : " This shared mailbox has no owner: add yourself under Shared access to open it in the mail client."}
+            </p>
+
             <div className="bg-surface border border-border rounded-md p-6">
                 <dl className="grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-3 text-sm">
                     <dt className="text-text-muted">Display name</dt>
@@ -161,17 +173,18 @@ function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & P
                 </div>
             </div>
 
-            <ShareAccessCard mailboxUid={mailbox.uid} ownerUserUid={mailbox.ownerUserUid} />
+            <ShareAccessCard mailboxUid={mailbox.uid} ownerUserUid={mailbox.ownerUserUid} currentUserUid={currentUserUid} />
 
             <EscrowScopeCard mailbox={mailbox} onUpdate={setMailbox} />
 
             {mailbox.isResource && <ResourceSettingsCard mailbox={mailbox} onUpdate={setMailbox} />}
 
-            <Modal open={confirmingAccess} onClose={closeAccessModal} title="Access this mailbox">
+            <Modal open={confirmingAccess} onClose={closeAccessModal} title="Impersonate this user">
                 <p className="text-sm mb-3">
                     You&rsquo;ll be signed in as <strong className="break-all">{mailbox.ownerUserUid}</strong>, the owner
                     of <strong className="break-all">{mailbox.primarySmtpAddress}</strong>, and see everything they can -
-                    and act as them, until you stop impersonating.
+                    and act as them, until you stop impersonating. This is the only way an administrator sees another
+                    user&rsquo;s mail.
                 </p>
                 {accessError && <Alert>{accessError}</Alert>}
                 <div className="flex gap-3 justify-end mt-5">
@@ -179,7 +192,7 @@ function MailboxDetailContent({ uid, impersonationBaseUrl }: { uid: string } & P
                         Cancel
                     </Button>
                     <Button type="button" className="!w-auto" loading={impersonating} disabled={impersonating} onClick={handleAccessMailbox}>
-                        Access mailbox
+                        Impersonate
                     </Button>
                 </div>
             </Modal>

package/apps/admin/quarantine/index.tsx

@@ -42,7 +42,8 @@ function QuarantineContent({ userUid }: { userUid?: string }) {
     function reload(uid: string) {
         setLoading(true);
         setError(null);
-        listQuarantine(uid, { page, limit: PAGE_SIZE })
+        // The administration scope: any mailbox's held mail, recorded in the audit log.
+        listQuarantine(uid, { page, limit: PAGE_SIZE, scope: "admin" })
             .then(setEntries)
             .catch((err) => setError(err instanceof ApiRequestError ? err.message : "Could not load quarantine."))
             .finally(() => setLoading(false));