@rapidmx/web-client 0.4.0 → 0.5.0

package/apps/shared/components/contacts/ContactsSidebar.tsx

@@ -47,6 +47,10 @@ export interface ContactsSidebarProps {
     contacts: Contact[];
     active: ContactsView;
     onSelect: (view: ContactsView) => void;
+    /** Whether to offer the "Deleted" view - restapi only honors `deleted=true` for a caller with delete and
+     * update rights on the mailbox (anyone else silently gets the live contacts), so the parent hides it
+     * otherwise. Defaults to `true`. */
+    showDeleted?: boolean;
     /** Bumped by the parent whenever a contact-list membership changes, so a newly-created/renamed list
      * shows up without a full page reload. */
     refreshToken?: number;
@@ -91,7 +95,7 @@ function NavItem({
  * server-side). Owns its own contact-list data-fetching, per this app's convention of keeping
  * `ContactsShellContext` itself minimal (mailbox/folder resolution only).
  */
-export default function ContactsSidebar({ mailboxUid, contacts, active, onSelect, refreshToken }: ContactsSidebarProps) {
+export default function ContactsSidebar({ mailboxUid, contacts, active, onSelect, refreshToken, showDeleted = true }: ContactsSidebarProps) {
     const [lists, setLists] = useState<ContactList[]>([]);
     const [listsError, setListsError] = useState<string | null>(null);
     const [addingList, setAddingList] = useState(false);
@@ -157,7 +161,7 @@ export default function ContactsSidebar({ mailboxUid, contacts, active, onSelect
             <div className="flex flex-col gap-0.5">
                 <NavItem label="Your contacts" count={contacts.length} active={active.type === "all"} onClick={() => handleSelect({ type: "all" })} />
                 <NavItem label="Favorites" count={favoriteCount} active={active.type === "favorites"} onClick={() => handleSelect({ type: "favorites" })} />
-                <NavItem label="Deleted" active={active.type === "deleted"} onClick={() => handleSelect({ type: "deleted" })} />
+                {showDeleted && <NavItem label="Deleted" active={active.type === "deleted"} onClick={() => handleSelect({ type: "deleted" })} />}
             </div>
 
             <div>

package/apps/shared/components/contacts/KeyChangeReview.tsx

@@ -0,0 +1,192 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useState } from "react";
+import { PinnedKeyChangedError, resolveKeyConflict, type KeyConflict } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { conflictSourceLabel, formatDate, groupFingerprint, keyChangeErrorMessage } from "./contactKeys.js";
+
+export interface KeyChangeReviewProps {
+    /** The mailbox whose contact holds the pinned key. */
+    mailboxUid: string;
+    /** The contact's address `resolveKeyConflict()` looks the contact up by; absent hides the actions. */
+    address?: string;
+    useType: "sign" | "encrypt";
+    /** Who the key belongs to, for the advice ("confirm with <name>"). */
+    ownerName: string;
+    /** The currently pinned key and when it was first trusted; absent (couldn't be loaded) hides the actions. */
+    current?: { fingerprint: string; since: number };
+    /** The new key: its fingerprint, the addresses its certificate names, and when and how it was recorded (absent when
+     * it's only known from the message being read). */
+    proposed: { fingerprint: string; emails?: string[]; observedAt?: number; source?: KeyConflict["source"] };
+    /** For accepting a key seen in a message: its certificate. Omitted, accepting pins the recorded conflict's key. */
+    certificate?: string;
+    /** Whether "Keep current key" applies - only when a conflict for this exact key is recorded. */
+    canReject: boolean;
+    /** `false` when the reader is known to lack the rights to change the contact's keys. */
+    canResolve?: boolean;
+    /** After a successful accept or reject - the caller refreshes what it shows. */
+    onResolved: (action: "accept" | "reject") => void;
+    /** After a 409: the pinned key changed meanwhile. The caller reloads and says so (`KEY_CHANGE_STALE_MESSAGE`). */
+    onPinnedKeyChanged: () => void;
+}
+
+/**
+ * The old-versus-new comparison for a changed contact key, with Accept new key (confirmed in a dialog) and Keep current
+ * key, calling `resolveKeyConflict()` against the pinned fingerprint shown. Shared by a message's "signing key changed"
+ * notice and a contact's recorded key conflicts.
+ */
+export default function KeyChangeReview({
+    mailboxUid,
+    address,
+    useType,
+    ownerName,
+    current,
+    proposed,
+    certificate,
+    canReject,
+    canResolve,
+    onResolved,
+    onPinnedKeyChanged,
+}: KeyChangeReviewProps) {
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    const [busy, setBusy] = useState<"accept" | "reject" | null>(null);
+    const [error, setError] = useState<string | null>(null);
+    const [forbidden, setForbidden] = useState(false);
+    const kind = useType === "sign" ? "signing" : "encryption";
+    const actionable = !!address && !!current && canResolve !== false && !forbidden;
+
+    async function resolve(action: "accept" | "reject") {
+        setBusy(action);
+        setError(null);
+        try {
+            await resolveKeyConflict(mailboxUid, {
+                address: address!,
+                useType,
+                action,
+                expectedPinnedFingerprint: current!.fingerprint,
+                ...(action === "accept" && certificate !== undefined ? { certificate } : {}),
+            });
+            setConfirmOpen(false);
+            onResolved(action);
+        } catch (err) {
+            setConfirmOpen(false);
+            if (err instanceof PinnedKeyChangedError) {
+                onPinnedKeyChanged();
+                return;
+            }
+            if (err instanceof ApiRequestError && err.status === 403) {
+                setForbidden(true);
+            }
+            setError(keyChangeErrorMessage(err));
+        } finally {
+            setBusy(null);
+        }
+    }
+
+    const proposedSeen =
+        proposed.observedAt !== undefined
+            ? `First seen ${formatDate(proposed.observedAt)}${proposed.source ? `, ${conflictSourceLabel(proposed.source)}` : ""}`
+            : "Only seen in this message";
+
+    return (
+        <div className="flex flex-col gap-2">
+            <dl className="grid grid-cols-1 sm:grid-cols-2 gap-2">
+                <div className="rounded-sm bg-surface p-2">
+                    <dt className="text-xs text-text-muted">Current key</dt>
+                    {current ? (
+                        <dd>
+                            <span className="font-mono text-xs break-all">{groupFingerprint(current.fingerprint)}</span>
+                            <span className="block text-xs text-text-muted">First seen {formatDate(current.since)}</span>
+                        </dd>
+                    ) : (
+                        <dd className="text-xs text-text-muted">The key you trust couldn&rsquo;t be loaded.</dd>
+                    )}
+                </div>
+                <div className="rounded-sm bg-surface p-2">
+                    <dt className="text-xs text-text-muted">New key</dt>
+                    <dd>
+                        <span className="font-mono text-xs break-all">{groupFingerprint(proposed.fingerprint)}</span>
+                        {proposed.emails && (
+                            <span className="block text-xs text-text-muted">
+                                Certificate for {proposed.emails.length > 0 ? proposed.emails.join(", ") : "no email address"}
+                            </span>
+                        )}
+                        <span className="block text-xs text-text-muted">{proposedSeen}</span>
+                    </dd>
+                </div>
+            </dl>
+            <p>
+                This is routine when {ownerName} renews a certificate, but it can also mean someone is impersonating them.
+                Confirm the new fingerprint with {ownerName} another way, such as a phone call, before accepting it.
+            </p>
+            {error && <Alert>{error}</Alert>}
+            {actionable && (
+                <div className="flex flex-wrap gap-2">
+                    <Button
+                        type="button"
+                        className="!w-auto"
+                        disabled={busy !== null}
+                        onClick={() => {
+                            setError(null);
+                            setConfirmOpen(true);
+                        }}
+                    >
+                        Accept new key
+                    </Button>
+                    {canReject && (
+                        <Button
+                            type="button"
+                            variant="secondary"
+                            className="!w-auto"
+                            loading={busy === "reject"}
+                            disabled={busy !== null}
+                            onClick={() => resolve("reject")}
+                        >
+                            Keep current key
+                        </Button>
+                    )}
+                </div>
+            )}
+            <Modal open={confirmOpen} onClose={() => busy === null && setConfirmOpen(false)} title="Accept the new key?">
+                <div className="flex flex-col gap-3 text-sm">
+                    <p>
+                        {useType === "sign"
+                            ? `Mail from ${address} signed with this key will show as verified.`
+                            : `Mail you send to ${address} will be encrypted to this key.`}{" "}
+                        The current {kind} key moves to this contact&rsquo;s key history.
+                    </p>
+                    <dl className="flex flex-col gap-1">
+                        <dt className="text-xs text-text-muted">New key fingerprint</dt>
+                        <dd className="font-mono text-xs break-all">{groupFingerprint(proposed.fingerprint)}</dd>
+                    </dl>
+                    <p className="text-text-muted">Only accept it once you&rsquo;ve confirmed this fingerprint with {ownerName}.</p>
+                    <div className="flex gap-3">
+                        <Button
+                            type="button"
+                            className="!w-auto"
+                            loading={busy === "accept"}
+                            disabled={busy !== null}
+                            onClick={() => resolve("accept")}
+                        >
+                            Accept new key
+                        </Button>
+                        <Button
+                            type="button"
+                            variant="secondary"
+                            className="!w-auto"
+                            disabled={busy !== null}
+                            onClick={() => setConfirmOpen(false)}
+                        >
+                            Cancel
+                        </Button>
+                    </div>
+                </div>
+            </Modal>
+        </div>
+    );
+}

package/apps/shared/components/contacts/contactKeys.ts

@@ -0,0 +1,78 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Display and error helpers for a contact's pinned keys and key changes (`KeyChangeReview`, `ContactDetailPane`,
+ * `MessageDetailPane`). */
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import type { Contact } from "@rapidmx/react-shared/contacts/contactsApi.js";
+import { PinnedKeyChangedError, type KeyConflict, type PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+
+export const KEY_CHANGE_STALE_MESSAGE = "This contact's keys changed while you were looking; reload to see the latest.";
+export const KEY_CHANGE_INVALID_MESSAGE =
+    "The new key isn't a valid, current certificate for this address, so it can't be accepted. Nothing was changed.";
+export const KEY_CHANGE_FORBIDDEN_MESSAGE = "You don't have permission to change this contact's keys.";
+export const KEY_CHANGE_NOT_FOUND_MESSAGE =
+    "There's no key change to resolve for this address any more. It may already have been resolved, or the contact was removed.";
+export const KEY_CHANGE_GENERIC_MESSAGE = "Couldn't update this contact's keys. Try again.";
+
+/** The error text for a failed `resolveKeyConflict()` other than `PinnedKeyChangedError` (which the caller reloads
+ * on and reports with `KEY_CHANGE_STALE_MESSAGE`). */
+export function keyChangeErrorMessage(err: unknown): string {
+    if (err instanceof PinnedKeyChangedError) {
+        return KEY_CHANGE_STALE_MESSAGE;
+    }
+    if (err instanceof ApiRequestError && err.status === 400) {
+        return KEY_CHANGE_INVALID_MESSAGE;
+    }
+    if (err instanceof ApiRequestError && err.status === 403) {
+        return KEY_CHANGE_FORBIDDEN_MESSAGE;
+    }
+    if (err instanceof ApiRequestError && err.status === 404) {
+        return KEY_CHANGE_NOT_FOUND_MESSAGE;
+    }
+    return KEY_CHANGE_GENERIC_MESSAGE;
+}
+
+/** Groups a fingerprint into 4-character blocks (`ab12 cd34 ...`), ignoring any separators it came with, so it can be
+ * read out and compared over another channel. */
+export function groupFingerprint(fingerprint: string): string {
+    const compact = fingerprint.replace(/[\s:]/g, "").toLowerCase();
+    return compact.match(/.{1,4}/g)?.join(" ") ?? compact;
+}
+
+/** Whether two fingerprints name the same key (case and separators ignored). */
+export function sameFingerprint(a: string | undefined, b: string | undefined): boolean {
+    return a !== undefined && b !== undefined && a.replace(/[\s:]/g, "").toLowerCase() === b.replace(/[\s:]/g, "").toLowerCase();
+}
+
+/** A revoked key's label: `"superseded"` for a routine replacement, `"revoked"` for a compromised key or one revoked
+ * with no reason; `undefined` when the key isn't revoked. */
+export function revocationLabel(key: PublicKey): "superseded" | "revoked" | undefined {
+    if (!key.revokedAt) {
+        return undefined;
+    }
+    return key.revocationReason === "superseded" ? "superseded" : "revoked";
+}
+
+/** Where a key conflict was observed, for display. */
+export function conflictSourceLabel(source: KeyConflict["source"]): string {
+    return source === "header" ? "from an incoming message" : "by key discovery";
+}
+
+/** restapi records `keysFirstSeen` on a contact but react-shared's `Contact` type doesn't carry it. */
+type ContactWithFirstSeen = Pick<Contact, "previousKeys"> & { keysFirstSeen?: number };
+
+/** When `key` (one of `contact`'s pinned keys) started being trusted: when it replaced the newest previous key of its
+ * use, else the contact's `keysFirstSeen`, else the key's own `notBefore`. */
+export function keyPinnedSince(contact: ContactWithFirstSeen, key: PublicKey): number {
+    const replaced = (contact.previousKeys ?? []).filter((previous) => previous.useType === key.useType).map((previous) => previous.replacedAt);
+    if (replaced.length > 0) {
+        return Math.max(...replaced);
+    }
+    return contact.keysFirstSeen ?? key.notBefore;
+}
+
+export function formatDate(ms: number): string {
+    return new Date(ms).toLocaleDateString();
+}

package/apps/shared/components/escrow/layout/EscrowShell.tsx

@@ -1,134 +1,148 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import "../../../styles/app.css";
-import React, { PropsWithChildren, ReactNode, useEffect, useState } from "react";
-import { HiOutlineClipboardDocumentList, HiOutlineFolderOpen } from "react-icons/hi2";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { listMatters } from "@rapidmx/react-shared/admin/mattersApi.js";
-import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
-import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
-import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
-import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "../../layout/BrandingChrome.js";
-import UserMenu from "../../layout/UserMenu.js";
-
-export type EscrowSection = "matters" | "auditLog";
-
-export interface EscrowShellProps {
-    active: EscrowSection;
-    userUid?: string;
-    authServerUrl?: string;
-}
-
-type Status = "checking" | "error" | "authorized";
-
-const NAV_ITEMS: NavItem[] = [
-    { id: "matters", href: "/escrow", label: "Matters", icon: HiOutlineFolderOpen },
-    { id: "auditLog", href: "/escrow/audit-log", label: "Audit Log", icon: HiOutlineClipboardDocumentList },
-];
-
-/**
- * Gates every `apps/escrow` page behind "is this an authenticated caller at all" — deliberately **not**
- * the same "does a canary endpoint 403 me" pattern `AdminShell` uses for the trusted `admin` role.
- * `specs/end-to-end_encryption.md`'s "Separation of duties" makes holder-ness a per-`EscrowScope` grant
- * (`EscrowScope.holderUserUids`), checked directly against `holderUserUids` in every restapi route that
- * needs it (`requireEscrowHolder()`) — never a role, and never global. There is no canary endpoint a
- * non-holder gets a clean 403 from: `GET /escrow/matters` (`BaseMatterRoute.find()`) returns `200 []` for
- * *any* authenticated caller who holds no scope at all, the same as it would for a holder of zero matters
- * — so unlike `AdminShell`, this shell cannot distinguish "holds nothing" from "holds no scope at all" up
- * front, and does not try to. It only confirms the caller is signed in and the API is reachable; every
- * actual holder-gated action (create a Matter, approve/deny a request, read material) is enforced
- * server-side and surfaces its own 403 `ApiRequestError` on the specific page that attempted it, same as
- * any other gated action elsewhere in this codebase. A non-holder who reaches `/escrow` simply sees an
- * empty Matters list and gets a real error if they try to act on something they don't hold — this is a
- * deliberate, documented scope trim rather than an oversight (see this session's own report on it).
- */
-export default function EscrowShell({ active, userUid, authServerUrl, children }: PropsWithChildren<EscrowShellProps>) {
-    const [status, setStatus] = useState<Status>("checking");
-    const [error, setError] = useState<string | null>(null);
-    const { branding, iconSrc } = useBranding();
-
-    useRedirectIfUnauthenticated(userUid, authServerUrl);
-
-    useEffect(() => {
-        if (!userUid) {
-            return;
-        }
-        // limit=1 - this call exists only to confirm the API is reachable for this signed-in caller, not
-        // to read any real data (every page below fetches its own data itself).
-        listMatters({ limit: 1 })
-            .then(() => setStatus("authorized"))
-            .catch((err) => {
-                setError(err instanceof ApiRequestError ? err.message : "Could not verify escrow console access.");
-                setStatus("error");
-            });
-    }, [userUid]);
-
-    function handleSignOut() {
-        window.location.href = authServerUrl ?? "/";
-    }
-
-    let content: ReactNode;
-    if (!userUid || status === "checking") {
-        content = <div className="min-h-screen" />;
-    } else if (status === "error") {
-        content = (
-            <div className="min-h-screen flex items-center justify-center p-8">
-                <div className="w-full max-w-md">
-                    <Alert>{error}</Alert>
-                </div>
-            </div>
-        );
-    } else {
-        const activeItem = NAV_ITEMS.find((item) => item.id === active);
-        content = (
-            <div className="min-h-screen flex flex-col bg-surface-alt">
-                <div className="flex-1 flex min-h-0">
-                    <nav
-                        aria-label="Escrow sections"
-                        className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1"
-                    >
-                        <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
-                        {NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (
-                            <a
-                                key={id}
-                                href={href}
-                                aria-label={label}
-                                aria-current={id === active ? "page" : undefined}
-                                title={label}
-                                className={[
-                                    "w-10 h-10 flex items-center justify-center rounded-sm",
-                                    id === active
-                                        ? "bg-primary/10 text-primary-dark"
-                                        : "text-text-muted hover:bg-surface-alt hover:text-text",
-                                ].join(" ")}
-                            >
-                                <Icon size={20} aria-hidden="true" />
-                            </a>
-                        ))}
-                    </nav>
-                    <BottomTabBar apps={NAV_ITEMS} active={active} />
-                    <div className="flex-1 flex flex-col min-w-0">
-                        <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
-                            <span className="font-display font-bold text-lg uppercase tracking-wide">{activeItem?.label}</span>
-                            <UserMenu userUid={userUid} authServerUrl={authServerUrl} onSignOut={handleSignOut} />
-                        </header>
-                        <div className="flex-1 pb-14 md:pb-0">
-                            <main className="max-w-6xl mx-auto px-6 py-8">{children}</main>
-                        </div>
-                    </div>
-                </div>
-            </div>
-        );
-    }
-
-    return (
-        <>
-            <BrandingHeader branding={branding} />
-            {content}
-            <BrandingFooter branding={branding} />
-        </>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import "../../../styles/app.css";
+import React, { PropsWithChildren, ReactNode, useEffect, useState } from "react";
+import { HiOutlineClipboardDocumentList, HiOutlineFolderOpen } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { listMatters } from "@rapidmx/react-shared/admin/mattersApi.js";
+import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
+import { getBranding } from "@rapidmx/react-shared/branding/brandingApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
+import UserMenu from "../../layout/UserMenu.js";
+import { signOutOfConsole } from "../../admin/signOut.js";
+
+export type EscrowSection = "matters" | "auditLog";
+
+export interface EscrowShellProps {
+    active: EscrowSection;
+    userUid?: string;
+    authServerUrl?: string;
+}
+
+type Status = "checking" | "error" | "authorized";
+
+const DEFAULT_ICON_SRC = "/images/logo.svg";
+
+const NAV_ITEMS: NavItem[] = [
+    { id: "matters", href: "/escrow", label: "Matters", icon: HiOutlineFolderOpen },
+    { id: "auditLog", href: "/escrow/audit-log", label: "Audit Log", icon: HiOutlineClipboardDocumentList },
+];
+
+/**
+ * Gates every `apps/escrow` page behind "is this an authenticated caller at all" — deliberately **not**
+ * the same "does a canary endpoint 403 me" pattern `AdminShell` uses for the trusted `admin` role.
+ * `specs/end-to-end_encryption.md`'s "Separation of duties" makes holder-ness a per-`EscrowScope` grant
+ * (`EscrowScope.holderUserUids`), checked directly against `holderUserUids` in every restapi route that
+ * needs it (`requireEscrowHolder()`) — never a role, and never global. There is no canary endpoint a
+ * non-holder gets a clean 403 from: `GET /escrow/matters` (`BaseMatterRoute.find()`) returns `200 []` for
+ * *any* authenticated caller who holds no scope at all, the same as it would for a holder of zero matters
+ * — so unlike `AdminShell`, this shell cannot distinguish "holds nothing" from "holds no scope at all" up
+ * front, and does not try to. It only confirms the caller is signed in and the API is reachable; every
+ * actual holder-gated action (create a Matter, approve/deny a request, read material) is enforced
+ * server-side and surfaces its own 403 `ApiRequestError` on the specific page that attempted it, same as
+ * any other gated action elsewhere in this codebase. A non-holder who reaches `/escrow` simply sees an
+ * empty Matters list and gets a real error if they try to act on something they don't hold — this is a
+ * deliberate, documented scope trim rather than an oversight (see this session's own report on it).
+ */
+export default function EscrowShell({ active, userUid, authServerUrl, children }: PropsWithChildren<EscrowShellProps>) {
+    const [status, setStatus] = useState<Status>("checking");
+    const [error, setError] = useState<string | null>(null);
+    const [iconSrc, setIconSrc] = useState(DEFAULT_ICON_SRC);
+
+    useRedirectIfUnauthenticated(userUid, authServerUrl);
+
+    // Only the icon is taken from branding here. The escrow console deliberately skips `useBranding()`, which
+    // would inject the custom stylesheet, and never renders the admin-configured header/footer HTML - this
+    // console handles escrow key material, so no admin-supplied markup or CSS runs on it.
+    useEffect(() => {
+        let cancelled = false;
+        getBranding()
+            .then((branding) => {
+                if (!cancelled) setIconSrc(branding.iconUrl || branding.logoUrl || DEFAULT_ICON_SRC);
+            })
+            .catch(() => {
+                // Decorative only - keep the default icon.
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        // limit=1 - this call exists only to confirm the API is reachable for this signed-in caller, not
+        // to read any real data (every page below fetches its own data itself).
+        listMatters({ limit: 1 })
+            .then(() => setStatus("authorized"))
+            .catch((err) => {
+                setError(err instanceof ApiRequestError ? err.message : "Could not verify escrow console access.");
+                setStatus("error");
+            });
+    }, [userUid]);
+
+    function handleSignOut() {
+        // Ends the auth-server session and tells other tabs, not just navigates - see `signOutOfConsole()`.
+        void signOutOfConsole(authServerUrl);
+    }
+
+    let content: ReactNode;
+    if (!userUid || status === "checking") {
+        content = <div className="min-h-screen" />;
+    } else if (status === "error") {
+        content = (
+            <div className="min-h-screen flex items-center justify-center p-8">
+                <div className="w-full max-w-md">
+                    <Alert>{error}</Alert>
+                </div>
+            </div>
+        );
+    } else {
+        const activeItem = NAV_ITEMS.find((item) => item.id === active);
+        content = (
+            <div className="min-h-screen flex flex-col bg-surface-alt">
+                <div className="flex-1 flex min-h-0">
+                    <nav
+                        aria-label="Escrow sections"
+                        className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1"
+                    >
+                        <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
+                        {NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (
+                            <a
+                                key={id}
+                                href={href}
+                                aria-label={label}
+                                aria-current={id === active ? "page" : undefined}
+                                title={label}
+                                className={[
+                                    "w-10 h-10 flex items-center justify-center rounded-sm",
+                                    id === active
+                                        ? "bg-primary/10 text-primary-dark"
+                                        : "text-text-muted hover:bg-surface-alt hover:text-text",
+                                ].join(" ")}
+                            >
+                                <Icon size={20} aria-hidden="true" />
+                            </a>
+                        ))}
+                    </nav>
+                    <BottomTabBar apps={NAV_ITEMS} active={active} />
+                    <div className="flex-1 flex flex-col min-w-0">
+                        <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
+                            <span className="font-display font-bold text-lg uppercase tracking-wide">{activeItem?.label}</span>
+                            <UserMenu userUid={userUid} authServerUrl={authServerUrl} onSignOut={handleSignOut} />
+                        </header>
+                        <div className="flex-1 pb-14 md:pb-0">
+                            <main className="max-w-6xl mx-auto px-6 py-8">{children}</main>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        );
+    }
+
+    return <>{content}</>;
+}