@rapidmx/web-client 0.30.0 → 0.31.0

package/lib/admin/escrowAuditLogApi.ts

@@ -13,7 +13,7 @@
  */
 
 import { ApiClient, withClient } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 
 export type { ListParams };
 
@@ -57,7 +57,7 @@ export interface EscrowAuditLogEntry {
  * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
  * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
 export function listAuditLogEntries(params: ListParams = {}, client?: ApiClient): Promise<EscrowAuditLogEntry[]> {
-    return withClient(client, `/escrow/audit-log?${buildQuery(params)}`);
+    return withClient(client, `/escrow/audit-log?${buildQuery(params, sortQuery({ sequence: "DESC" }))}`);
 }
 
 export function getAuditLogEntry(uid: string, client?: ApiClient): Promise<EscrowAuditLogEntry> {

package/lib/admin/escrowScopesApi.ts

@@ -12,7 +12,7 @@
  */
 
 import { ApiClient, withClient } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 import type { ResolvedPrincipal } from "../mail/mailboxAccessApi.js";
 
 export type { ListParams };
@@ -53,7 +53,7 @@ export interface EscrowScope {
  * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
  * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
 export function listEscrowScopes(params: ListParams = {}, client?: ApiClient): Promise<EscrowScope[]> {
-    return withClient(client, `/escrow/scopes?${buildQuery(params)}`);
+    return withClient(client, `/escrow/scopes?${buildQuery(params, sortQuery({ uid: "ASC" }))}`);
 }
 
 /**

package/lib/admin/pluginsApi.ts

@@ -37,6 +37,25 @@ export interface PluginManifest {
 
 export type PluginSettingValue = string | number | boolean;
 
+/** What `@rapidmx/restapi` answers in place of the saved value of a setting whose key names a secret (secret, password, credential, token, api key), so a
+ * stored API key or shared secret never reaches the console. Sent back as it was given, it means "left alone": the saved value stays. */
+export interface PluginSecretSetting {
+    secret: true;
+}
+
+/** A saved setting as a response shows it. */
+export type PluginSavedSetting = PluginSettingValue | PluginSecretSetting;
+
+/** Whether `value` is the placeholder a saved secret setting is shown as. */
+export function isSecretSetting(value: unknown): value is PluginSecretSetting {
+    return typeof value === "object" && value !== null && (value as { secret?: unknown }).secret === true;
+}
+
+/** Whether a setting's key names a secret - mirrors `@rapidmx/restapi`'s `SECRET_SETTING_KEY`, which decides what it withholds. */
+export function isSecretSettingKey(key: string): boolean {
+    return /secret|password|credential|token|api_?key/i.test(key);
+}
+
 /** Mirrors `@rapidmx/restapi`'s `PluginConfiguredSetting`: what the deployment's own configuration (the command line, the
  * environment, the server's defaults) says about one setting. It applies until a value is saved, which wins over it. */
 export interface PluginConfiguredSetting {
@@ -54,7 +73,7 @@ export interface Plugin {
     packageVersion: string;
     integrity?: string;
     enabled: boolean;
-    settings: Record<string, PluginSettingValue>;
+    settings: Record<string, PluginSavedSetting>;
     /** For each setting the deployment's configuration provides a value for, what it says. Absent from a server that
      * predates it, which reads as nothing being configured. */
     configured?: Record<string, PluginConfiguredSetting>;
@@ -216,7 +235,7 @@ export interface UpdatePluginInput {
     packageVersion?: string;
     enabled?: boolean;
     /** A `null` value clears a setting back to the plugin's own default. */
-    settings?: Record<string, PluginSettingValue | null>;
+    settings?: Record<string, PluginSavedSetting | null>;
     /** What a previewed version change or enable was confirmed to also install and enable. */
     expectedPlan?: PluginExpectedPlan;
 }

package/lib/admin/retentionPolicyApi.ts

@@ -27,6 +27,10 @@ export interface RetentionPolicy {
  * the server enforces this regardless. */
 export const MIN_AUDIT_LOG_RETENTION_DAYS = 2190;
 
+/** The server-enforced floor for `messageRetentionDays` (30 days) - `MIN_MESSAGE_RETENTION_DAYS` in `@rapidmx/restapi`, mirrored here for the same reason as
+ * `MIN_AUDIT_LOG_RETENTION_DAYS`. A shorter period is refused with a 400. */
+export const MIN_MESSAGE_RETENTION_DAYS = 30;
+
 /** `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. */

package/lib/admin/transportRulesApi.ts

@@ -10,7 +10,7 @@
  */
 
 import { ApiClient, withClient } from "../util/api.js";
-import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { ListParams, buildQuery, sortQuery } from "../util/apiQuery.js";
 
 export type { ListParams };
 
@@ -53,7 +53,7 @@ export interface TransportRule {
  * 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 listTransportRules(params: ListParams = {}, client?: ApiClient): Promise<TransportRule[]> {
-    return withClient(client, `/mail/transport-rules?${buildQuery(params)}`);
+    return withClient(client, `/mail/transport-rules?${buildQuery(params, sortQuery({ sequence: "ASC", uid: "ASC" }))}`);
 }
 
 export function getTransportRule(uid: string, client?: ApiClient): Promise<TransportRule> {

package/lib/appearance/preferencesApi.ts

@@ -19,7 +19,7 @@
  * Everything that comes from outside - the response, a push event, the page's server-rendered props, `localStorage` - goes through
  * `normalizeAppearance()`, which keeps only well-formed values (so a stale or hostile value can never reach a CSS declaration).
  */
-import { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+import { ApiClient, ApiRequestError, apiUrl, withClient, withClientRaw } from "../util/api.js";
 
 export type AppearanceMode = "system" | "light" | "dark";
 export type BackgroundKind = "none" | "color" | "image";
@@ -283,19 +283,8 @@ export async function saveAppearance(update: AppearanceUpdate, client?: ApiClien
 
 /** Stores `file` (already checked with `validateBackgroundFile()`) as the background: its raw bytes, with its own content type - which
  * bypasses `apiFetch()`, as it always sends JSON. Answers with the updated preferences. */
-export async function uploadAppearanceBackground(file: Blob): Promise<AppearancePreferences> {
-    const res = await fetch(apiUrl(`${PATH}/background`), {
-        method: "POST",
-        credentials: "include",
-        headers: withCsrfHeader({ "Content-Type": file.type || "application/octet-stream" }),
-        body: file,
-    });
-    const contentType = res.headers.get("content-type") ?? "";
-    const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
-    if (!res.ok) {
-        const message = (body && (body.message || body.error)) || res.statusText || "Upload failed.";
-        throw new ApiRequestError(message, res.status, body?.code);
-    }
+export async function uploadAppearanceBackground(file: Blob, client?: ApiClient): Promise<AppearancePreferences> {
+    const body = await withClientRaw(client, `${PATH}/background`, "POST", file, file.type || "application/octet-stream");
     const stored = normalizeAppearance(body);
     if (!stored) {
         throw new ApiRequestError("The server did not return the saved appearance.", 502);

package/lib/auth/session.ts

@@ -25,9 +25,36 @@ export const SESSION_REFRESH_CHECK_MS = 60 * 1000;
 /** A reload that follows a successful recovery refresh but still finds no session is not repeated within this window. */
 export const SESSION_RELOAD_GUARD_MS = 60 * 1000;
 
+/** A refresh answered with a refusal is asked once more after this long, in case the cookies were rotated by another tab or the server's session save lagged. */
+export const SESSION_REFRESH_RETRY_MS = 1500;
+/** A forced refresh (a request was refused, or the page has no session) does nothing when a refresh succeeded within this long: the refusal came from the old cookies. */
+export const SESSION_REFRESH_MIN_GAP_MS = 10 * 1000;
+/** How many entries `rapidmx.session.log` keeps. */
+export const SESSION_LOG_MAX = 40;
+
 const LOCK_NAME = "rapidmx-session-refresh";
 const REFRESHED_AT_KEY = "rapidmx.session.refreshedAt";
 const RELOADED_AT_KEY = "rapidmx.session.reloadedAt";
+const LOG_KEY = "rapidmx.session.log";
+
+/**
+ * How long a refresh request may go unanswered before it is given up on (not aborted - see `postRefresh()`). A refresh runs inside a cross-tab Web Lock, so one that hangs would hold the lock - and
+ * with it every tab's refresh, and every request waiting on a recovery - for good.
+ */
+export const SESSION_REFRESH_TIMEOUT_MS = 15 * 1000;
+
+let retryDelayMs = SESSION_REFRESH_RETRY_MS;
+let refreshTimeoutMs = SESSION_REFRESH_TIMEOUT_MS;
+
+/** Sets how long a refresh request may go unanswered (for tests); `resetSessionRecovery()` restores the default. */
+export function setSessionRefreshTimeout(ms: number): void {
+    refreshTimeoutMs = ms;
+}
+
+/** Sets how long a refused refresh waits before its one retry (for tests); `resetSessionRecovery()` restores the default. */
+export function setSessionRefreshRetryDelay(ms: number): void {
+    retryDelayMs = ms;
+}
 
 function readTimestamp(storage: () => Storage, key: string): number {
     try {
@@ -46,34 +73,186 @@ function writeTimestamp(storage: () => Storage, key: string, value: number): voi
     }
 }
 
+/** Whether a refresh succeeded within the last `ms`, in this tab or another (they share `localStorage`). A cleared or future-dated record counts as no. */
+export function refreshedRecently(ms: number): boolean {
+    const at = readTimestamp(() => localStorage, REFRESHED_AT_KEY);
+    const age = Date.now() - at;
+    return at > 0 && age >= 0 && age < ms;
+}
+
+/** One entry of the session log (`rapidmx.session.log`). */
+export interface SessionLogEntry {
+    /** When it happened, ISO 8601. */
+    t: string;
+    /** What happened, e.g. `refresh:start`, `refresh:rejected`, `leave`. */
+    e: string;
+    /** A short detail (a reason, a status, an age). Never a token or cookie value. */
+    d?: string;
+}
+
+/** The session log: the last `SESSION_LOG_MAX` things the silent refresh did, oldest first, kept in `localStorage['rapidmx.session.log']` so the cause of an unexpected sign-in can be read afterward. */
+export function getSessionLog(): SessionLogEntry[] {
+    try {
+        const value = JSON.parse(localStorage.getItem(LOG_KEY) ?? "[]");
+        return Array.isArray(value) ? value : [];
+    } catch {
+        return [];
+    }
+}
+
+/** Appends to the session log, dropping the oldest entries past `SESSION_LOG_MAX`. Best effort: blocked storage loses the entry. */
+export function logSessionEvent(e: string, d?: string): void {
+    try {
+        const entries = getSessionLog();
+        entries.push(d === undefined ? { t: new Date().toISOString(), e } : { t: new Date().toISOString(), e, d });
+        localStorage.setItem(LOG_KEY, JSON.stringify(entries.slice(-SESSION_LOG_MAX)));
+    } catch {
+        // The log is evidence only; it must never get in the way of the session.
+    }
+}
+
+/** How long ago the last successful refresh was, for log entries: `12s`, or `never` when this browser has no record. */
+function sinceLastRefresh(): string {
+    const at = readTimestamp(() => localStorage, REFRESHED_AT_KEY);
+    return at > 0 ? `${Math.round((Date.now() - at) / 1000)}s` : "never";
+}
+
 /** The URL of auth-server's sign-in page, carrying the current URL as `return_to` so it can send the browser back here. */
 function signInUrl(authServerUrl: string): string {
     return `${authServerUrl}/auth/signin?return_to=${encodeURIComponent(window.location.href)}`;
 }
 
+/** Sends the browser to auth-server's sign-in page, first writing why to the session log and printing the log to the console. */
+function goToSignIn(authServerUrl: string, reason: string): void {
+    logSessionEvent("leave", `${reason} sinceOk=${sinceLastRefresh()}`);
+    console.info("[rapidmx] Going to sign-in. Session log:", getSessionLog());
+    window.location.href = signInUrl(authServerUrl);
+}
+
+/** Why a refresh was made, for the session log. */
+export type SessionRefreshReason = "check" | "recovery" | "nouser";
+
+/** Whether `err` says auth-server rejected the refresh token itself, as opposed to a failure worth retrying. */
+function isAuthRejection(err: unknown): boolean {
+    return err instanceof ApiRequestError && (err.status === 401 || err.status === 403);
+}
+
+function describeFailure(err: unknown): string {
+    if (err instanceof ApiRequestError) {
+        return `status=${err.status}${err.code ? ` code=${err.code}` : ""} sinceOk=${sinceLastRefresh()}`;
+    }
+    return `${err instanceof Error ? err.message : "unknown"}`.slice(0, 80);
+}
+
+/** Counts the refresh requests made, so a request that answers after it was given up on can tell whether a newer one has started since. */
+let refreshSeq = 0;
+
+/**
+ * One `POST /auth/refresh`, recording when it succeeded. Given up on after `SESSION_REFRESH_TIMEOUT_MS`, which is a failure worth retrying, not a rejection.
+ * Giving up only stops waiting: the request is NOT aborted. Auth-server rotates the single-use refresh token as it answers, and a browser that aborts before the
+ * response headers arrive never stores the rotated cookie, leaving the consumed token behind - the next refresh would be refused and the user signed out.
+ * A late answer is still logged, and a late success still recorded unless a newer refresh has started since.
+ */
+async function postRefresh(authServerUrl: string): Promise<void> {
+    const seq = ++refreshSeq;
+    const request = authApiFetch(authServerUrl, "/auth/refresh", { method: "POST" });
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new Error(`refresh timed out after ${refreshTimeoutMs}ms`));
+        }, refreshTimeoutMs);
+    });
+    // Handles the request's own outcome whenever it comes, so a rejection after the timeout is never unhandled.
+    request.then(
+        () => {
+            if (!timedOut) {
+                return;
+            }
+            if (seq === refreshSeq) {
+                writeTimestamp(() => localStorage, REFRESHED_AT_KEY, Date.now());
+                logSessionEvent("refresh:late-ok");
+            } else {
+                logSessionEvent("refresh:late-superseded");
+            }
+        },
+        (err) => {
+            if (timedOut) {
+                logSessionEvent("refresh:late-error", describeFailure(err));
+            }
+        },
+    );
+    try {
+        await Promise.race([request, timeout]);
+    } finally {
+        clearTimeout(timer);
+    }
+    writeTimestamp(() => localStorage, REFRESHED_AT_KEY, Date.now());
+}
+
+let refreshing: { promise: Promise<boolean>; forced: boolean } | undefined;
+
 /**
  * Refreshes the signed-in session through auth-server: exchanges the `refresh` cookie for a new access token and
  * refresh token, both set as cookies on the response. Rejects with the `ApiRequestError` auth-server answered
  * (`401`/`403` when the refresh token has expired or was revoked).
  *
- * A refresh token is single-use and bound to the session, so two tabs refreshing at once would make the second one look
- * like a dead session. Refreshes are therefore serialised across tabs (Web Locks, where the browser has them) and each
- * tab records when the last one happened, so a tab that gets its turn right after another tab refreshed does nothing.
+ * A refresh token is single-use and bound to the session, and auth-server saves the rotated token a moment after it
+ * answers, so refreshing twice in quick succession makes the second look like a dead session. Refreshes are therefore
+ * shared by every caller in the tab (one in flight at a time), serialised across tabs (Web Locks, where the browser has
+ * them), and each tab records when the last one succeeded, so a caller that gets its turn right after a refresh does
+ * nothing. A refresh that is refused is asked once more after `SESSION_REFRESH_RETRY_MS` (the cookies may have been
+ * rotated meanwhile) before it counts as a rejection.
  *
- * @param force Refresh even when the last refresh, by this tab or another, was recent.
+ * @param force Refresh even when the last refresh, by this tab or another, was `SESSION_REFRESH_AFTER_MS` ago or less. Even forced, a refresh made within `SESSION_REFRESH_MIN_GAP_MS` is not repeated.
+ * @param reason Why, for the session log.
  * @returns `true` when a refresh was made, `false` when one was not needed.
  */
-export async function refreshSession(authServerUrl: string, force = false): Promise<boolean> {
+export function refreshSession(authServerUrl: string, force = false, reason: SessionRefreshReason = force ? "recovery" : "check"): Promise<boolean> {
+    if (refreshing) {
+        // A forced caller must not take the outcome of a refresh that may have been skipped as not due: ask again once it is over (which the minimum gap keeps from being a second POST when it did refresh).
+        return force && !refreshing.forced ? refreshing.promise.then(() => refreshSession(authServerUrl, true, reason)) : refreshing.promise;
+    }
     const run = async (): Promise<boolean> => {
-        if (!force && Date.now() - readTimestamp(() => localStorage, REFRESHED_AT_KEY) < SESSION_REFRESH_AFTER_MS) {
+        if (refreshedRecently(force ? SESSION_REFRESH_MIN_GAP_MS : SESSION_REFRESH_AFTER_MS)) {
+            if (force) {
+                logSessionEvent("refresh:skip", `recent sinceOk=${sinceLastRefresh()} reason=${reason}`);
+            }
             return false;
         }
-        await authApiFetch(authServerUrl, "/auth/refresh", { method: "POST" });
-        writeTimestamp(() => localStorage, REFRESHED_AT_KEY, Date.now());
+        logSessionEvent("refresh:start", `reason=${reason} sinceOk=${sinceLastRefresh()}`);
+        try {
+            await postRefresh(authServerUrl);
+        } catch (err) {
+            if (!isAuthRejection(err)) {
+                logSessionEvent("refresh:error", describeFailure(err));
+                throw err;
+            }
+            logSessionEvent("refresh:rejected", `${describeFailure(err)} attempt=1`);
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+            if (refreshedRecently(SESSION_REFRESH_MIN_GAP_MS)) {
+                // Another tab renewed the session while this one waited.
+                logSessionEvent("refresh:skip", `recent-after-retry-wait reason=${reason}`);
+                return false;
+            }
+            logSessionEvent("refresh:retry", `reason=${reason}`);
+            try {
+                await postRefresh(authServerUrl);
+            } catch (err2) {
+                logSessionEvent(isAuthRejection(err2) ? "refresh:rejected" : "refresh:error", `${describeFailure(err2)} attempt=2`);
+                throw err2;
+            }
+        }
+        logSessionEvent("refresh:ok", `reason=${reason}`);
         return true;
     };
     const locks = typeof navigator === "undefined" ? undefined : navigator.locks;
-    return locks ? locks.request(LOCK_NAME, run) : run();
+    const promise = (locks ? locks.request(LOCK_NAME, run) : run()).finally(() => {
+        refreshing = undefined;
+    });
+    refreshing = { promise, forced: force };
+    return promise;
 }
 
 /** How long the outcome of a recovery is reused for: requests that fail together share one refresh, and a session that will not come back is not asked again at once. */
@@ -83,9 +262,10 @@ let recovery: Promise<boolean> | undefined;
 let lastRecovery: { at: number; renewed: boolean } | undefined;
 
 /**
- * Renews the session because a request was refused for lack of one, whatever this browser's record of the last refresh says. Every request
- * refused at about the same time shares one refresh, and its outcome is reused for `SESSION_RECOVERY_COOLDOWN_MS`. A refusal also clears the record of
- * the last refresh, so the next regular check asks again (and sends the browser to sign-in if the refresh token is truly gone).
+ * Renews the session because a request was refused for lack of one, whatever this browser's record of the last refresh says - except that a refresh that
+ * succeeded within `SESSION_REFRESH_MIN_GAP_MS` (by this tab or another) is not repeated: the request was refused with the cookies from before it, so it is
+ * simply sent again with the new ones. Every request refused at about the same time shares one refresh, and its outcome is reused for `SESSION_RECOVERY_COOLDOWN_MS`.
+ * A refusal also clears the record of the last refresh, so the next regular check asks again (and sends the browser to sign-in if the refresh token is truly gone).
  *
  * @returns Whether the session was renewed.
  */
@@ -93,7 +273,7 @@ export function recoverSession(authServerUrl: string): Promise<boolean> {
     if (lastRecovery && Date.now() - lastRecovery.at < SESSION_RECOVERY_COOLDOWN_MS) {
         return Promise.resolve(lastRecovery.renewed);
     }
-    recovery ??= refreshSession(authServerUrl, true)
+    recovery ??= refreshSession(authServerUrl, true, "recovery")
         .then(
             () => true,
             () => {
@@ -109,15 +289,13 @@ export function recoverSession(authServerUrl: string): Promise<boolean> {
     return recovery;
 }
 
-/** Forgets what recoveries have done (for tests). */
+/** Forgets what recoveries and refreshes have done, and restores the retry delay and timeout (for tests). */
 export function resetSessionRecovery(): void {
     recovery = undefined;
     lastRecovery = undefined;
-}
-
-/** Whether `err` says auth-server rejected the refresh token itself, as opposed to a failure worth retrying. */
-function isAuthRejection(err: unknown): boolean {
-    return err instanceof ApiRequestError && (err.status === 401 || err.status === 403);
+    refreshing = undefined;
+    retryDelayMs = SESSION_REFRESH_RETRY_MS;
+    refreshTimeoutMs = SESSION_REFRESH_TIMEOUT_MS;
 }
 
 /**
@@ -140,7 +318,7 @@ export function useRedirectIfUnauthenticated(userUid: string | undefined, authSe
             console.error("Cannot redirect to sign-in: mail:auth_server_url is not configured.");
             return;
         }
-        window.location.href = signInUrl(authServerUrl);
+        goToSignIn(authServerUrl, "no-session");
     }, [userUid, authServerUrl, explicitClient]);
 }
 
@@ -171,9 +349,11 @@ export interface SessionRefreshOptions {
  * - `userUid` set: also renews the session when a request is refused for lack of one (`apiFetch()` asks `recoverSession()` and sends the request
  * again), so a token that ran out while timers were stopped costs nothing. Refreshes once the token is `SESSION_REFRESH_AFTER_MS` old (and right away when this browser has no
  * record of a recent refresh, since the page's token age is unknown), checked every `SESSION_REFRESH_CHECK_MS` and
- * whenever the tab becomes visible or the network returns, because a sleeping laptop stops timers. A failure that is
- * not a rejection is simply retried at the next check. A rejection (`401`/`403`: the refresh token expired or was
- * revoked, so the session cannot be kept) redirects to sign-in with `return_to` after `options.beforeRedirect` has run.
+ * whenever the tab becomes visible or focused or the network returns, because a sleeping laptop stops timers (a tab that wakes after the
+ * token's hour checks first, and a request refused meanwhile waits for that same refresh rather than starting its own). A failure that is
+ * not a rejection is simply retried at the next check. A rejection (`401`/`403` twice running, `SESSION_REFRESH_RETRY_MS` apart: the refresh
+ * token expired or was revoked, so the session cannot be kept) redirects to sign-in with `return_to` after `options.beforeRedirect` has run.
+ * Everything it does is recorded in the session log (`getSessionLog()`), which is also printed to the console when the browser goes to sign-in.
  *
  * **A no-op under an `ApiClientContext.Provider`** (see `util/apiClientContext.ts`): everything above assumes a
  * `jwt`/`refresh` cookie pair this app can renew through auth-server's own `/auth/refresh` - meaningless for a
@@ -205,21 +385,26 @@ export function useSessionRefresh(userUid: string | undefined, authServerUrl: st
         let cancelled = false;
 
         if (!userUid) {
-            if (paused || Date.now() - readTimestamp(() => sessionStorage, RELOADED_AT_KEY) < SESSION_RELOAD_GUARD_MS) {
-                window.location.href = signInUrl(authServerUrl);
+            if (paused) {
+                goToSignIn(authServerUrl, "no-session paused");
                 return;
             }
-            // Forced: the page has no session, so what this browser remembers of the last refresh says nothing about whether one is due.
-            refreshSession(authServerUrl, true)
+            if (Date.now() - readTimestamp(() => sessionStorage, RELOADED_AT_KEY) < SESSION_RELOAD_GUARD_MS) {
+                goToSignIn(authServerUrl, "no-session after-reload");
+                return;
+            }
+            // Forced: the page has no session, so what this browser remembers of the last refresh says nothing about whether one is due (but one made seconds ago is not repeated).
+            refreshSession(authServerUrl, true, "nouser")
                 .then(() => {
                     if (!cancelled) {
+                        logSessionEvent("reload-after-refresh");
                         writeTimestamp(() => sessionStorage, RELOADED_AT_KEY, Date.now());
                         window.location.reload();
                     }
                 })
                 .catch(() => {
                     if (!cancelled) {
-                        window.location.href = signInUrl(authServerUrl);
+                        goToSignIn(authServerUrl, "no-session refresh-rejected");
                     }
                 });
             return () => {
@@ -236,26 +421,32 @@ export function useSessionRefresh(userUid: string | undefined, authServerUrl: st
 
         let leaving = false;
         let inFlight = false;
-        const leave = async () => {
+        let hiddenAt: number | undefined;
+        const leave = async (reason: string) => {
             leaving = true;
+            logSessionEvent("leave:pending", reason);
             try {
                 await beforeRedirectRef.current?.();
             } catch {
                 // Saving what can be saved is best effort; the session is over either way.
             }
             if (!cancelled) {
-                window.location.href = signInUrl(authServerUrl);
+                goToSignIn(authServerUrl, reason);
             }
         };
-        const check = () => {
+        // `trigger` names what woke the check, for the log; the periodic tick passes none, so it logs only when it actually refreshes.
+        const check = (trigger?: string) => {
             if (cancelled || leaving || inFlight) {
                 return;
             }
+            if (trigger) {
+                logSessionEvent("check", trigger);
+            }
             inFlight = true;
-            refreshSession(authServerUrl)
+            refreshSession(authServerUrl, false, "check")
                 .catch((err) => {
                     if (isAuthRejection(err)) {
-                        void leave();
+                        void leave("refresh-rejected");
                     }
                 })
                 .finally(() => {
@@ -263,21 +454,30 @@ export function useSessionRefresh(userUid: string | undefined, authServerUrl: st
                 });
         };
         const onVisible = () => {
-            if (document.visibilityState === "visible") {
-                check();
+            if (document.visibilityState === "hidden") {
+                hiddenAt = Date.now();
+                return;
             }
+            logSessionEvent("visible", hiddenAt === undefined ? "hiddenFor=unknown" : `hiddenFor=${Date.now() - hiddenAt}ms`);
+            hiddenAt = undefined;
+            check("visible");
         };
+        const onFocus = () => check("focus");
+        const onOnline = () => check("online");
+        const onTick = () => check();
 
-        check();
-        const interval = window.setInterval(check, SESSION_REFRESH_CHECK_MS);
+        check("mount");
+        const interval = window.setInterval(onTick, SESSION_REFRESH_CHECK_MS);
         document.addEventListener("visibilitychange", onVisible);
-        window.addEventListener("online", check);
+        window.addEventListener("focus", onFocus);
+        window.addEventListener("online", onOnline);
         return () => {
             cancelled = true;
             setApiSessionRecovery(undefined);
             window.clearInterval(interval);
             document.removeEventListener("visibilitychange", onVisible);
-            window.removeEventListener("online", check);
+            window.removeEventListener("focus", onFocus);
+            window.removeEventListener("online", onOnline);
         };
     }, [userUid, authServerUrl, paused, explicitClient]);
 }

package/lib/branding/brandingApi.ts

@@ -9,7 +9,7 @@
  * it); every write is `@RequiresTrustedRole()` on the backend.
  */
 
-import { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+import { ApiClient, withClient, withClientRaw } from "../util/api.js";
 
 export interface Branding {
     companyName: string;
@@ -52,36 +52,24 @@ export function updateBranding(input: UpdateBrandingInput, client?: ApiClient):
     });
 }
 
-async function uploadBrandingAsset(path: string, file: File): Promise<Branding> {
-    const res = await fetch(apiUrl(path), {
-        method: "POST",
-        credentials: "include",
-        headers: withCsrfHeader({ "Content-Type": file.type || "application/octet-stream" }),
-        body: file,
-    });
-    const contentType = res.headers.get("content-type") ?? "";
-    const responseBody = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
-    if (!res.ok) {
-        const message = (responseBody && (responseBody.message || responseBody.error)) || res.statusText || "Upload failed.";
-        throw new ApiRequestError(message, res.status, responseBody?.code);
-    }
-    return responseBody as Branding;
+function uploadBrandingAsset(path: string, file: File, client?: ApiClient): Promise<Branding> {
+    return withClientRaw(client, path, "POST", file, file.type || "application/octet-stream");
 }
 
 /** Uploads `file` as the logo, self-hosted via `BlobStore` — bypasses `apiFetch` (which always forces
  * `Content-Type: application/json`) the same way `mailApi.ts`'s `uploadAttachment()` does, since
  * `BaseBrandingRoute.uploadLogo()` reads the raw request body directly. */
-export function uploadBrandingLogo(file: File): Promise<Branding> {
-    return uploadBrandingAsset("/system/branding/logo", file);
+export function uploadBrandingLogo(file: File, client?: ApiClient): Promise<Branding> {
+    return uploadBrandingAsset("/system/branding/logo", file, client);
 }
 
 /** Uploads `file` as the compact nav-header icon, independently of `uploadBrandingLogo()`'s full logo. */
-export function uploadBrandingIcon(file: File): Promise<Branding> {
-    return uploadBrandingAsset("/system/branding/icon", file);
+export function uploadBrandingIcon(file: File, client?: ApiClient): Promise<Branding> {
+    return uploadBrandingAsset("/system/branding/icon", file, client);
 }
 
-export function uploadBrandingStylesheet(file: File): Promise<Branding> {
-    return uploadBrandingAsset("/system/branding/stylesheet", file);
+export function uploadBrandingStylesheet(file: File, client?: ApiClient): Promise<Branding> {
+    return uploadBrandingAsset("/system/branding/stylesheet", file, client);
 }
 
 export function deleteBrandingLogo(client?: ApiClient): Promise<void> {

package/lib/calendar/calendarApi.ts

@@ -151,6 +151,8 @@ export interface CalendarEvent {
 
 const LIST_PAGE_SIZE = 500;
 const LIST_CALENDAR_EVENTS_MAX_PAGES = 100;
+/** Without an order, a page boundary can skip or repeat an event: the `uid` is a fixed one. */
+const EVENT_SORT = JSON.stringify({ uid: "ASC" });
 
 /**
  * Lists every event in a folder (same "fetch the flat list, filter client-side" contract as
@@ -173,7 +175,7 @@ export async function listCalendarEvents(folderUid: string, client?: ApiClient):
     for (let page = 0; page < LIST_CALENDAR_EVENTS_MAX_PAGES; page++) {
         const batch = await withClient<CalendarEvent[]>(
             client,
-            `/mail/calendar-events?${buildQuery({ limit: LIST_PAGE_SIZE, page }, { folderUid })}`,
+            `/mail/calendar-events?${buildQuery({ limit: LIST_PAGE_SIZE, page }, { folderUid, sort: EVENT_SORT })}`,
         );
         events.push(...batch);
         if (batch.length < LIST_PAGE_SIZE) {